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Installation Guide for d-tree V3.1 
DEVELOPMENT TOOLBOX 


©1988 Faircom 
ALL RIGHTS RESERVED 


1.1 GENERAL 


The purpose of this Installation Guide is to facilitate the creation of your d-tree 
libraries, utilities and example programs. There are three main steps: 

@® prepare the source code 

e compile the source code 

e create libraries and executables 


Be sure to examine the Start Up Guide. In particular, check to see if any source 
code changes are required. If so, apply these changes to the source files after 
copying them to your disk but before compiling. 


Be sure to examine the READ.ME file in the root directory of Disk 1. Also, notice 
the following sub-directories on Disk 4 which cover the more popular operating 
environments. 

@ \xenix - xenix operation system. 

e \unix - unix operation system. 

e \msc_ - Miscrosoft Compiler(DOS) 

e \turboc - Turbo C (DOS-Borland) 

e \lattice - Lattice C (DOS) 


Examine any READ.ME file which may be present in the sub- directory pertain- 
ing to your particular environment. Utilization of the make or project file in the 
appropriate sub-directory will make the installation process much easier. If your 
environment has not been covered, refer to the General Installation section for 
assistance. 


SEE PAGE 1-14 for MOST COMMON ERRORS if you have any problems 
during installation, compilation or execution. 
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1.2 Compatibility with Other FairCom Products 
ALL ENVIRONMENTS MUST TAKE NOTE 


It is necessary to have the c-tree™ File Handler installed before you may use 
the d-tree Development Toolbox. We suggest installing other FairCom 
products, such as the c-tree™ File Handler and optionally the r-tree™ Report 
Generator , in sister directories. For example: 

c:\ctree 

c:\rtree 

c:\dtree 
Reference the c-tree and r-tree Installation Guide for detailed installation in- 
structions. 
The following c-tree modifications must be applied before installing d-tree. 


All tems - Single and Multi 
e CATALOG - NOTFORCE 

Because the d-tree CATALOG program does perform rebuilding of 
files, it is necessary to link this particular program using a buffered 
version of the c-tree library. A buffered (single user) library is 
accomplished by setting the I/O protocol to NOTFORCE in CTOPTN.H 
before compiling the library modules. 
NOTE: If you require a multi-user (non-buffered) environment, it is 
recommended that you create a separate multi-user library to be used 
with your multi-user applications. 


e MAX_KEY SEG 7 
The variable MAX_KEY_SEG found within CTOPTN.H must allow for 
at least seven key segments per index. Make certain this entry appears 
as MAX_KEY_SEG 7 (or greater). For more information on key 
segments see the c-tree documentation. 


DOS Systems Only 
e LARGE MEMORY MODEL- To take full advantage of all the facilities of 
the "catalog" program it is necessary to use the LARGE memory 
model option when creating the "catalog" program. 


e Due to the code size of the "catalog" program it may be necessary to 
reduce the "sort space" used by the index rebuild procedures. This 
may be accomplished by editing the #define SORT_SPACE in the 
c-tree file ctibld.c to appear as: 

#define SORT_SPACE 16380 

(This is only required for the library used by the catalog. You may start 
by leaving it as is, but remember this if your rebuild procedure fails 
due to lack of memory.) 
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1.3 MS/PC-DOS SYSTEM INSTALLATION 


STEP 1: File Transfer 
Select the drive (e.g. C) and directory (e.g. \dtree) in which to place the d-tree 


source code. Place Disk 1 in floppy drive A. Type the following command line: 
(note the spaces between words. C and \dtree are two separate variables 
passed to the batch file.) 


a:dtree C (\dtree 


The batch file dtree.bat will automatically build the necessary directory and sub- 
directories and copy the source into these directories, prompting you to change 
disks. After the files have been copied as described above, you will have the fol- 
lowing configuration on your selected hard disk directory: 


e c:\dtree - contains the system independent code, headers, 
d-tree scripts and utilities 

e c:\dtree\xenix - Xenix specific code and headers 

e c:\dtree\unix - Unix specific code and headers 

e c:\dtree\msc - Microsoft C specific code and headers 

e c:\dtree\turboc - TurboC specific code and headers 

e c:\dtree\lattice - Lattice C specific code and headers 

e c:\dtree\instant - Instant Screen code 


(direct screen memory access) 


NOTE: These files could be created on any drive and with any root directory. 
For example, if you make \SRC your current working directory on drive E, then 


type 


a:dtree E dtree 


E:\SRC\DTREE will be the root directory for your d-tree installation. 
All of these sub-directories include make files or project files to create the dtree 
utilities and example programs. 


NOTE: If you do not wish to install all of these sub-directories, see GENERAL IN- 
STALLATION. 
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TEP2: Set Envi t Vari 
Most of the DOS compilers use the INCLUDE and LIB environment variables to 
specify the directories for system headers and run-time libraries, respectively. 
Before compiling, be sure to properly set these environment variables based on 
your compiler's specifications. d-tree must also have available the location of 
the c-tree and optionally the r-tree header files. This is identified via the set in- 
clude command. This command may be issued at the command line or within 
the AUTOEXEC.BAT file. 


C> set INCLUDE = \include;\include\sys;\ctree;\rtree 


The global system variable TERM must also be set to the appropriate terminal 
defined in the "termcap" file. For most DOS systems, type the command line 


C> set TERM=DOS 
or for color monitor 
C> set TERM=DOSCOLOR 


or place the same command in the AUTOEXEC.BAT file. (note: reference the 
‘termcap”" section in the reference guide for further discussion of the "termcap" 
file and utilities.) 


d-tree screen control in the dos environment can be controlled in two ways: 
either by the use of the ANSI.SYS device driver or by writing directly to video 
memory. 
ANSLSYS driver- Load this driver in the CONFIG.SYS file as follows: 

(load this driver for initial setup) 
DEVICE = ANSI.SYS 


INSTANT SCREENS - to activate the direct memory video access, set the 
#define INSTANT in "dt_defin.h". This will activate the direct video logic. 
Simply comment this #define out to de-activate on non-memory mapped 
machines. 


STEP 3: Testing d-1 iti 


COMPILE AND EXECUTE THE PROGRAM "dt tests.c" 
TO VERIFY ALL HEADER SETTINGS ARE CORRECT 
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STEP 4: Creating Libraries: The next step is to compile the d-tree modules, 


create a d-tree library, and create some executable d-tree programs. This can 
be done with either the provided "make" file, or a standard dos batch file. Both 
are mentioned below. Use one or the other. 


In DOS systems you must specify a memory model for the compilation. At this 
time the supplied "make" file should be edited to verify that the proper sub-direc- 
tories are utilized to reference c-tree and r-tree header files. The provided setup 
assumes ..\ctree and ..\rtree. Also check the c-tree and r-tree library names 
used in the provided make. They are defined by CTLIB and RTLIB in the make. 
To initiate the make in a Microsoft C environment, access the c:\dtree\msc 
directory and then type: 


C:\dtree\msc > MAKEDT L 


to create a large memory mode set up. This will cause the LDT (large dtree) sub- 
directory to be created and used for all the object files and executables as well 
as the dtree library (called DTREEL.LIB). (That is, c:\dtree\msc\Lat will contain 
the results of the make.) 

The d-tree "catalog" requires that the large memory model be used. The 
"catalog" will only be created if the large model was selected. 

Use the large memory model, for initial installation, to compile the "catalog" 
program. This will allow you to take full advantage of all the features the 
"catalog" provides as well as allow you to complete the d-tree TUTORIAL. After 
becoming more familiar with the d-tree tools you may wish to utilize other 
memory models. When the large model is selected DTCATLOG.LIB along with 
DTCATLOG.EXE will be created. 


We have provided batch files or in some cases, project files, (Turbo C) to be 
used instead of make files. In the appropriate directory, review the file 
DTLALL.BAT or files ending with .prj. 


STEP 5 - Complete the Installation: After completing the compilation proceed 
to COMPETE THE INSTALLATION to insure your system is installed properly. 
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1.4 XENIX SYSTEM INSTALLATION 


Step 1 - File Transfer: Select the sub-directory in which to install d-tree 
(e.g.,/usr/dtree). Once you have made this your current working directory, place 
Disk 5 in your floppy Drive A. Then type the following command line: 

doscp a:/xenix/dosmovet ./ 

doscp a:/xenix/dosmove2 ./ 

doscp a:/xenix/dosmove3 ./ 

doscp a:/xenix/dosmoveé4 ./ 

doscp a:/xenix/dosmove5 ./ 


Then place Disk 1 in your floppy Drive A and type 
sh dosmovet 


which will copy the files from Disk 1 to the dtree directory. Then place Disk 2 in 
floppy Drive A and type: 
sh dosmove2 


which will copy the files from Disk 2 to the dtree directory. Then place Disk 3 in 
floppy Drive A and type: 
sh dosmove3 


which will copy the files from Disk 3 to the dtree directory. Then place Disk 4 in 
floppy Drive A and type: 
sh dosmove4 


which will copy the files from Disk 4 to the dtree directory. Then place Disk 5 in 
floppy Drive A and type: 

sh dosmove5 

which will copy the remaining files required for Xenix installation. 


- ine: Once the files are copied to your machine, edit 


the file "dt_defin.h" as remove the #define DOS which is located at the top of 
this file. 


COMPILE AND EXECUTE THE PROGRAM "dt tests.c" 
TO VERIFY ALL HEADER SETTINGS ARE CORRECT 
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STEP 4 - Creating Libraries: The next step is to compile the d-tree modules, 


create a d-tree library, and create some executable d-tree programs. This can 
be done with either the provided make file, or a standard batch file. Both are 
mentioned below. Use one or the other. 


Make File 

At this time the supplied "make" file should be edited to verify that the proper 
sub-directories are utilized to reference c-tree and r-tree header files. The 
provided setup assumes ..\ctree and ..\rtree. Also verify the library names used 
in the make represented by the CTLIB and RTLIB symbols. 


To make the XENIX applications, execute the shell 


sh makedt L 


which will create a d-tree application library using the large model in the file 
/usr/lib/Llibdtree.a, place the d-tree objects in /usr/dtree/Ldt (large d-tree) and 
place the d-tree executable utilities in /usr/bin. 

The d-tree catalog requires that the large memory model be used. The "catalog" 
will only be created if the large model was selected. 

Use the large memory model, for initial installation, to compile the "catalog" 
program. This will allow you to take full advantage of all the features the 
"catalog" provides as well as allow you to complete the d-tree TUTORIAL. After 
becoming more familiar with the d-tree tools you may wish to utilize other 
memory models. When the large model is selected /lib/Llibdtcatlog.a along 
with /usr/bin/dtcatlog will be created. 

The d-tree application libraries have been named so that you may use the com- 
mand line reference 

-ldtree 


-Idtcatlog 


for the library while linking an application program. 
In general, the directory structure for d-tree is as follows: 


/usr/dtree d-tree source files 
/lib d-tree libraries 
/usr/bin executable modules 


/usr/dtree/Ldt d-tree object modules 


Batch Files: There is provided a batch file called “dtreeall" along with a file 
called "ccc" which may be used to compile the modules without using a make 
utility. View these files to verify settings (compiler switches, paths, etc.) before 
using them. 


STEP 5: After completing the compilation proceed to COMPLETE THE INSTAL- 
LATION to insure your system is installed properly. 
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1.5 UNIX SYSTEM INSTALLATION 


STEP 1 - File Transfer: To install d-tree on a UNIX system from a DOS dis- 
kette, you must have a communications program to connect a DOS and UNIX 
machine, or a host program (such as pcdsk) which can read DOS diskettes. In 
either case, be sure that the carriage return characters are stripped-off the 
source lines as the code is imported. 


The files to copy from the DOS diskettes are as follows: 
e all the files on Disks 1,2, 3 and 4 
e all the files in the root directory of Disk 5 
@ all the files in the UNIX sub-directory of Disk 5 
e if you do not have r-tree, all the files in the rtreehdr directory on disk 4. 


Step 2 - Case Sensitivity: Once the files have been ported to your Unix d-tree 
directory, (ie: /usr/dtree) check to see if the file names are in UPPER or lower 


case. If they are in UPPER case, use the shellscript 
sh ./chgcase -I * 
to change the names to lower case (the "chgcase" shell is on disk 5). 


TEP 3 - Remove D fine: Once the files are copied to your machine, edit 
the file "dt_defin.h". Remove the #define DOS which is located at the top of this 
file. 


TEP 4 - Check d-tr ttin 


COMPILE AND EXECUTE THE PROGRAM "dt tests.c" 
TO VERIFY ALL HEADER SETTINGS ARE CORRECT 


STEP 5 - Create Libraries: The next step is to compile the d-tree modules, 
create a d-tree library, and create some executable d-tree programs. This can 
be done with either the provided make file, or a standard batch file. Both are 
mentioned below. Use one or the other. 


Make File; 

At this time the supplied make file should be edited to verify that the proper sub- 
directories are utilized to reference c-tree and r-tree header files. The provided 
setup assumes ..\ctree and ..\rtree. Aiso verify the c-tree and r-tree library 
names represented by the CTLIB and RTLIB symbols. 
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To make the UNIX applications, execute the shell: 


$ sh makedt 


which will create a d-tree application library in the file /usr/lib/libdtree.a, the 
"catalog" library in the file /usr/lib/libdtcatlog.a, and place the d-tree objects in 
/usr/dtree/dt , with the d-tree executables in /usr/bin. 


The d-tree application libraries have been named so that you may use the 
-ldtree 

-ldtcatlog 

command line reference for the library while linking an application program. 


IF YOUR UNIX ENVIRONMENT REQUIRES MEMORY MODEL SPECIFICA- 
TIONS, then examine how the Xenix shells incorporate a memory model 
parameter. 

In general, the directory structure for d-tree is as follows: 


/usr/dtree d-tree source files 

/lib d-tree libraries 
/ustr/bin executable modules 
/usr/dtree/dt d-tree object modules 


Batch Files: There is provided a batch file called “dtreeall" along with a file 
called "ccc" which may be used to compile the modules without using a make 
utility. View these files to verify settings (compiler switches, paths, etc.) before 
using them. 


STEP 6 - Complete the Installation: After completing the compilation proceed 
to COMPLETE THE INSTALLATION to insure your system is installed properly. 
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1.6 GENERAL INSTALLATION 


‘l Don't Have a MAKE " 
For the developer who prefers to compile without the assistance of make files, 
we Offer the following assistance. 


STEP 1 - File Transfer: If you do not want all the files from the distribution dis- 
kettes to be installed, then you may copy a subset of the files. The root direc- 
tories of Disk 1, Disk 2, Disk 3 and Disk 4 contain the system independent 
modules. These modules are necessary for all installations. Then you may 
choose the appropriate sub-directory on Disk 5 for the remaining files. it you do 
not have r-tree the header files in the rtreehdr directory on disk 4 must be 
copied. 


STEP 2- NON DOS MACHINES ONLY: Once the files are copied to your 
machine, edit the file “dt_defin.h" as remove the #define DOS which is lo- 
cated at the top of this file. 


Step 3 - Check d-tree settin 
COMPILE AND EXECUTE THE PROGRAM "dt tests.c" 
TO VERIFY ALL HEADER SETTINGS ARE CORRECT 
Step 4 - d-tree LIBRARY: Create the dtreel.lib (large model ) by compiling the 


following modules: 


1. DT_IMAGE.c 2. DTPIMAGE.c 3. DT_ALIGN.c 
4. DT FIELD.c 5. DTPFIELD.c 6. DT _MISCl.c 
7. DT CONST.c 8. DIPCONST.c 9. DT WDODA.c 
10. DT_PRMPT.c 11. DTPPRMPT.c 12. DT_UTILY.c 
13. DT _SUBFL.c 14. DTPSCANN.c 15. DT_REFMT.c 
16. DT _EDITS.c 17. DTPSUBFL.c 18. DT FREEE.c 
19. DT_DFALT.c 20. DTPEDITS.c 21. DT PSTFX.c 
22. DT_CALCS.c 23. DITPDFALT.c 24. DT_TOKEN.c 
25. DT_HELPP.c 26. DTPKEYBD.c 27. DT_TSPLT.c 
28. DT_MAPIT.c 29. DTPIFILS.c 30. DT_DEBUG.c 
31. DT_IFILS.c 32. DTPCALCS.c 33. DT_PARSE.c 
34. DT_KEYBD.c 35. DTPHELPP.c 36. DT COMPL.c 
37. DT DODTS.c 38. DTPMAPIT.c 39. DT_COMPI.c 
40. DT _DORTS.c 41. DT ERROR.c 42. DT_RELAT.c 
43. DT MENUS.c 44. DITPMENUS.c 45. DT_XTRCT.c 
46. DT_RTREE.c 47. DIPRTREE.c 48. DT SPTRS.c 
49. DT_CALMP.c 50. DTPTABLE.c 51. DT INOUT.c 
52. DT EVALU.c 53. DTPHOOKS.c 54. DT GROUP.c 
55. DT_GENRL.c 56. DTPGROUP.c 57. DT_INPUT.c 
58. DT HOOKS.c 59. DT_CTREE.c 60. DT_FRAME.c 
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61. DT FUNCT.c 62. DT SCANN.c 63. DT EMAND.c 
64. DT_EFILL.c 65. DT _EDATE.c 66. DT_ETABL.c 

67. DT EDUPK.c 68. DT _EVALD.c 69. DT_GROUT.c 
70. DT ADDMD.c 71. DT_CHGMD.c 72. DT MANMD.c 


73. DT MSDOS.c(dos only) 

Note: There are dos batch files in the sub-directory on disk 5 called “dtlall.bat" 
which may be used to create the library. For unix/xenix there is a file called 
"dtreeall" which uses the file "ccc" that can be used for compilation. 


Step 5 - Create CATALOG LIBRARY: Create the CATALOG library by compil- 


ing the following modules: 


1. DTCATCSP.c 5. DTCATADI.c 

2. DICATADO.c 6. DTCATWAT.c 

3. DTCATDIF.c 7. DTCATINC.c 

4. DTCATSEL.c 8. DICATVRT.c 
A 


Create the executable files by compiling and linking the following source files to 
the indicated libraries. Use of the large model is required on DOS machines un- 
less otherwise noted. There is a simple batch file using microsoft which can be 

used as a guide. This batch file (dtexe.bat") can be found in the msc subdirec- 
tory on disk 5. 


e dt doque.c - Process Compile Que Program. 
No Libraries Needed. Small Model Ok. 
(NOTE: This executable must be named “dt_doque.exe" 
EVEN ON NON-DOS Machines. This is because that is 
the name given in the "dt_compl.h" file which is used to 
call this program within d-tree . If you do not want to call 
it this, change the name in “dt_compl.h". See next page.) 


e dt_catalog.c - Catalog Program. 
Link with dtcatlog , d-tree, and c-tree libraries. 


e dt catvd.c - Validation Dictionary Program. 
Link with d-tree and c-tree libraries. 


e dt score.c - "run" Program (d-tree super core). 
Link with d-tree, r-tree(optional), and c-tree libraries. 


e dt bhelp.c - Build help text index Program. 
Link with d-tree and c-tree libraries. 
e dtcatrpt.c - Catalog report program. 
Link with d-tree , r-tree and c-tree libraries. 
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1.7 COMPLETE THE INSTALLATION 


tep 1 - Check batch fil sed for compiling: As you begin to work with d- 
tree you will find that there are options to compile programs during develop- 
ment. There is a group of batch files that are called from within certain 
programs to accomplish this. The names of these batch files are defined in the 
d-tree header file called "dt_compl.h". This file is shown below: 


dt_compl.h 
/* batch file compile definitions */ 

define DTCOMPILE “compile. bat” program compile batch file */ 
tdefine DTCATQUE ‘“‘dtcompil. que” compile que file */ 

tdefine DTPQNAME ‘dt_doque. exe” process compile que program name */ 
tdefine DTCOMP_P ‘‘dtcomp_p. bat” batch file for “run” pgm -c compile 


option-parareter files pgm */ 
tdefine DTCOMP_I ‘‘dtcomp_i.bat” batch file for “run” pgm —c compile 
option-increrental files pgm */ 


We have placed versions of these batch files in the various subdirectories. If you — 
experience problems when selecting a compile option within d-tree, we sug- 
gest you verify the following files: 


compile.bat dtcomp i-.bat dtcomp _p.bat 


Note: We use the .bat extension in all environments. These names can be 
changed in "dt_compl.h". UNIX/XENIX: make these batch files executable as fol- 
lows: 


$ chmod +x compile.bat 
$ chmod +x dtcomp i.bat 
$ chmod +x dtcomp _p.bat 


SPECIAL NOTE: In these batch files we have made two assumtions which need 
to be verified. 


1) we have set up these batch files assuming you have r-tree. If you do not have 
r-tree, remove any reference to r-tree in the link statements. By r-tree references 
we mean any reference to rtintr.obj or to a r-tree library (rtalib or rtsglib) 


2) the primary methid of running r-tree scripts is in the interpreted mode. In 
order to make the batch files simpler, we have assumed that the interpreted ver- 
sion of the report function call (rtintr.obj) has been placed in the r-tree library. 
Either do the same or modify the batch file to include rtintr.obj on the link line. 


Si RCC a ea ee ee 
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STEP 2 - Environment Variables: After completing the compilation as directed 


for your particular environment make sure that your environment variable TERM 
has been set as follows: 


DOS- 

C> set TERM=DOS or C> set TERM=DOSCOLOR for color. 
XENIX - 

$ TERM =ansi;export TERM 

UNIX - 


$ TERM =vt100;export TERM 

(NOTE: substitute "ansi" or “vt100" with the appropriate terminal. Associated 
entry must be found in “termcap" file. See “termcap" section if more information 
is necessary). 


STEP 2 - Run the dt_catvd Program (MANDATORY): To test the installation 


run the "dt_catvd" program: 
C>dt_catvd 


Select the IMPORT DATA option on the menu. This will load the catalog’s 
validation dictionary with data from the text file "dt_catvd.txt". Once import is 
finished, select option 2, at the prompt enter a zero (0). This will show you a list 
of valid codes. If this is the case, everything appears to be set up ok. Press 
"ESC ESC" to return to prompt, ESC ESC again to return to menu. Then press 
"ESC ESC" to return to operating system. This import process MUST BE 
DONE in order for the catlog program to work properly. The codes that are 
imported into this file are used to validate proper entry into the catalog. 


STEP 3 - Build Help Text Index: The index over the help text file must be built 
to allow the HELP ability to function in the CATALOG program. Execute the 
program "dt_bhelp" to build this index. 


STEP 4 - If Problems: If no errors occur , proceed to the d-tree tutorial, else 
see next page for help. 
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1.8 MOST COMMON PROBLEMS 


The following is a list of possible error messages you may receive if the setup is 
not correct. 


1) 


2) 


3) 


4) 


5) 


6) 


"Error occurred during TERMCAP parse Error = 7201" 
The "termcap" file is not found in the proper disk and directory. 


"Error occurred during TERMCAP parse Error = 7202" 
The system global variable TERM has not been set or the value it has 
been set to is not found as a terminal definition in the "termcap' file. 


Data Improperly Positioned on the Screen 
DOS: Make sure ANSI.SYS is in the CONFIG.SYS. 


NON-DOS:If you are operating in a non-DOS environment and the data on 
the screen is not properly positioned, refer to the TERMCAP section 
within the REFERENCE MANUAL. 


All libraries , d-tree, r-tree (optional), and c-tree, must be compiled in 
LARGE memory model. 


Unresolved errors during link: 


a) chkidx unresolved - the c-tree module ctdbug.c must be compiled 
and placed in the c-tree library. See page 1-2 


b) dtype or report unresolved - the r-tree function report is being 
called in the program. It needs to find the module rtintr.obj to 
resolve these definitions. Either place rtintr.obj in your r-tree 

library or place it one the link line. See special note on page 1-12 


Error 109 when running a d-tree program. You forgot to set 
MAX_KEY_SEG in c-tree as mentioned on page 1-2. 


UNIX Problems - Make sure that all of d-tree has been compiled with 
the #define DOS taken out of dt_defin.h. 


eee 
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2.1 The "RUN" Program - Tutorial 


Often the best way to learn how to use a tool of any sort is to actually use it. 
Accordingly, the purpose of this section is to provide a step by step illustration 
of d-tree in action. The objective in doing this is to provide a hands-on example 
of the power and flexibility of some aspects of d-tree. Enough of an example 
that you, the user, feel comfortable using d-tree for simple applications. This 
should also provide a platform for further investigation of the various aspects of 
d-tree to the extent you feel necessary. 


For our purposes of illustrating d-tree in action, we will develop a small but rela- 
tively complete application. We call this application the Small Project Account- 
ing System (SPAS). Following are some brief specifications of this system. 
More details will be provided as needed. 


The purpose of the Small Project Accounting System is to record transactions 
such as deposits made and checks written along with classification data as to 
type of income or expense, the project to which the income/expense is related, 
and customer/vendor involved in the transaction. Once these transactions are 
collected, they must be able to be reviewed (both on-screen and on paper), and 
updated. Finally, programs must be able to extract various items of information 
and create usable reports. 


Information for SPAS will be organized into the following files: 


e Customer Master File...customer information 

e Project Master File........ project codes and descriptions 

e Vendor Master File........ vendor information 

e Account Code File......... ledger account codes and descriptions 
e Transaction File............. financial transactions 

e Distribution File............. distribution of trans to accounts 
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Let’s begin our development by creating a file maintenance program for the Cus- 
tomer Master File. Let’s assume that this file contains the following fields: 


e Customer ID 

e Customer Name 

e Customer Address (2 lines) 

e Customer City 

e Customer State 

e Customer ZIP Code 

e Customer Phone Number 

e Customer Type Code 

e Customer Initial Entry Date 

e Customer payments year to date 


We will use a utility program provided with d-tree called "run". This utility as- 
sists in quickly generating file maintenance applications. Keep in mind that d- 
tree provides several methods by which to develop programs. We are currently 
illustrating only one. 


To get started, we use our text editor or word processor (be sure that you are 
able to create pure text or ASCII files, such as non-document mode in Word- 
Star). Create a file named "customer.dts". (The file extension, ".dts", stands for 
d-tree script.) We will use the editor to create a sample layout of the screen to 
be used for data input and display. Only a few special characters must be 
known for you to do this. 


First, data fields will be positioned and sized by the use of underscore ("_") 
characters. Each underscore is assumed to represent a position for the data 
field. Additional characters, when used with the underscore, define other 
aspects of the data field. 


For our first example we will need only one additional field definition character - 
the period or decimal point ("."). When the decimal point is positioned in a field, 
it indicates that the field is of type real (or floating point). The location of the 
decimal point identifies the number of decimal digits which are to follow the 
decimal point in the Values contained and displayed in this field. For example, if 
_ our field specification is " .___", d-tree assumes that we wish to have a real 
value with five integer digits and two decimal digits (for example, 00000.01 to 
99999.99). 
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Another special screen image definition character is the at-sign ("@"). This 
character is used to identify any of several special system values which can be 
placed on the screen form. 


The current values are: 


e "@DATE" the current system date 

e "@TIME" the current system time 

e "@CWD" the current working directory 

e "@RRNO" the current relative record number 
(requires special handling) 

e "@SEQ" the c-tree unique record sequence number 


(requires special handling) 


The only other special character for screen layouts is the plus sign ("+"). It is 
used to draw frames on an image. Placing a "+" where you desire the top left 
corner of a frame, and then placing an additional "+" at the bottom right will 
define a frame to d-tree. Up to nine frames per image are allowed (note: multi- 
ple images per screen are allowed; in addition, this limit of nine can be in- 
creased if necessary). Additional frame corners are distinguished by tagging a 
number to the plus sign ("+ 2"...."+3"...etc.). Frame titles can also be defined in 
the following format. 

+ 2This is my Title 


+2 
This will define a second frame and center the title. 


Except for these special characters, we may describe the data items, label 

~ columns, present instructions, etc. as desired. As you will soon see, the "run" 
program will create a number of default screens. Each of these screens will be 
given a default (two line) title. This (two line ) title is copied from your screen. 

In other words, the first two lines you paint in your screen must represent a title. 
See example. (Note: This is not a limitation within d-tree as a whole. All screens 
are not required to have two line titles. This is only used by d-tree’s "run" 
program.) 


OK, let’s build our screen image. Using the following field lengths to aid you, 
simply type the screen as shown on the next page with your favorite editor. 


Customer ID: 10 Phone: 14 
Name: 40 Type: 3 
Address: 40 Last Trans Date: 6 
City: 20 Balance: 8,2 
State 2 
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eb tS epee hema 
; customer.dts 
@DATE Small Project Accounting System @TINE 
Customer Master Maintenance 


Customer Id: 


Name: 

Address: 

City: State: _ Zip: 
Phone: Customer Type Code: 
Last Transaction Date: Customer Balance: 


Once the screen image is entered and saved we are ready to work with "run". 
Before starting the program, however, be sure that you have an environment 
variable properly set for your terminal type. For most DOS systems, this can be 
done from a DOS prompt by typing: 


C>set TERM=DOS 
(or place this command in autoexec.bat) 


You can verify the current setting by typing: 
C>set 


See your Operating System documentation for further information on environ- 
ment variables. Be sure that the "termcap" file from the d-tree distribution disks 
has been properly installed. (See "d-tree Installation Procedures") 


NOTE: On non-DOS systems, you will need to set their TERM environment vari- 
able to a corresponding entry in the d-tree TERMCAP file. Example: xenix or 
unix terminals can be set as follows: 


$ TERM =ansi; export TERM 
The terminal identifier “ansi" can be replaced with proper terminal (wyse50, etc. ) 


Assuming d-tree has been properly installed, you access "run" by entering the 
command "run" followed by the screen image file name ("customer.dts") at a 
system prompt: 


C> run customer.dts 
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After a few seconds, you should see a menu something like: 


A S 
Customer Master Maintenance 


. Add Records 

. Change“View Records 
. Delete Record 

. Print Records 


Option:(C 


This menu, completely generated by "run", identifies the four main activities pos- 
sible in the file maintenance program which has been generated: Add, 
Change/View, Delete, and Print. As we will see later, these menu item descrip- 
tions, as well as much of what was generated with default values, can be easily 
changed. Note that the screen heading (the first two lines) is taken as the first 
two lines of our initial screen image. 


To check out our file maintenance program, select "Add Records", option 1. 
The next screen that you see should look familiar. It should look something like 
this: 


Sun May 22 Small Project Accounting Systen 15:39:@6S 
Customer Master Maintenance 


Customer Id:C 

Name: 

Address: 

City: State: — Zip: 


Phone: Customer Type Code: 


Last Transaction Date: Customer Balance: 
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Notice that the field which is expected to be entered is enclosed in square 
braces ('[ ]"). For the purpose of checking out the File Maintenance Program, 
enter the following data values: (leave the date and balance fields blank). 


Cust Id Name Address City State Zip Phone [ype 


11223 Olson, M. 123 Pe Or. Los Angeles , Ca. 12346 816-665-7865 B 
12345 Lemons, Alice 1895 Carter Dr. Reno, Nv. 89502 702-322-0238 A 
72636 Heady, Janice 212 Code Ave, Mesa, Az. 65340 602-765-2243 C 


Note that as you enter data, you stay in the Add mode. After you "field exit" 
from the last field, you get a message to "PRESS RETURN to POST". This is a 
"catch" option prior to writing to disk. The HOME key can be used to return to 
the top of the current entry form. It is not necessary to have the user get all the 
way to the last field in the image in order to post. From any field in the entry 
form you may use the POST key (for DOS press the END key on numeric 
keypad) to go immediately to the post message: 


Once these data records are entered, let’s look at the other options from the 
menu. To do this, exit out of the "ADD" mode by pressing the escape key twice. 
Back at the Customer Master Maintenance Menu, select option 2 
("Change/View Records"). With this option you can select an individual record 
to view and/or update. Optionally, you may see a list of all (or a specified sub- 
set) of the records currently in the file. After making the selection for option 2, 
you should see a screen similar to this: 


un May ma Project Accounting System 
Customer Master Maintenance 


Enter Desired Record Key: C J 


Press ESC ESC to EXIT 
FairCom (c) 1988 
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This is called the prompt screen. If you wish to retrieve a specific record and 
you know the key value (for our application, the Customer ID), you simply enter 
the desired key value. That record will then be displayed. 


lf you are not sure which record you wish to retrieve, you may enter zero ('0") 
for the key value. The entry here is used as a "target" field to access the file by 
its key. A value of zero for the target will allow you to browse through a list of all 
records in the file for the access will start with the first record in the file. (note: a 
greater than or equal to access is called). Using this method, the next screen 
will look something like this: 


A g 
Customer Master Maintenance 


Select 
1 11223 Olsen, HM. 
iza fo Dr, Los Angeles 
123456 816-665-7865 B 
1234S Lemons, Alice 
1839S Carter Dr. Reno 
89582 7@2-322-6238 Aa 
72636 Heady, Janice 
212 Code Ave Mesa 
65346 682-765-2243 CG 


lf you wanted records whose key begins with "2", enter "2" instead of "0". This 
method may be used to start listing records somewhere other than the begin- 
ning of the file. The PAGE UP and PAGE DOWN keys allow movement through 
the file by "pages" (or screens). The ARROW keys may also be used to move 
the displayed list up or down in smaller increments. 


At this point, you can select a record to process further by specifying its option 
number. The selected record will then be displayed in our screen image format. 
Try both the direct and browse methods of retrieving records. 


The Record DELETE option allows the user to remove a data record from the 
file. The record may be selected in the same ways that were used for 
Change/Review option. After the record is located and displayed, you are asked 
if this record is to be deleted. Pressing return at this prompt will delete the 
record, pressing "ESC ESC" will return without deleting. | 
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The Print Option requires that you have the r-tree library installed. The "run" 
program prepares a default r-tree script providing a listing of the contents of the 
data file. If you have installed r-tree, try option 4 which will generate a default r- 
tree report directed to your screen. Just for fun, return to your editor and look 
at the r-tree script created by "run". Its name is "customer.rts". See all the 
grunt work we've saved you! This provides an excellent base to start from in 
building more complex reports. 


Review 
In this session we created a file maintenance program by first describing the 
screen image we wish to use for the addition, update, and deletion of records to 
our file. We used several special characters to describe our screen image, such 
as: 


e (underscore) indicates a placeholder for a data field 
@ "@" (at-sign) indicates the beginning of a system value 
@. (period) indicates a decimal point in a floating field 
e + (plus sign) indicates a corner of a frame 


Once we have entered and saved the screen image, we start the "run" program 
with the command line entry: 


C> run customer.dts 


We are then performing file maintenance over a file containing the data fields 
described in our screen image. We are able to add, change/view, delete, and 
print records. 


A great amount of work can be accomplished with little effort. This is a sample 
of the strength of d-tree. 


Exercise (NOTE: in order to complete next sessions this must be done) 

1. Create another File Maintenance Program for the Project Master File. Call the 
d-tree script file "project.dts". When you have it completed, save it and use 
"run" to see how it works. The Project Master File contains the following fields: 


Project Code ( 5 positions) 
Project Type ( 3 positions) 
Description (40 positions) 
Contact (20 positions) 
Start Date ( 6 positions) 
End Date ( 6 positions) 
YTD Expenses ( 8.2 format for dollars and cents) 
YTD Income ( 8.2 format for dollars and cents) 
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d-tree Tutorial - Session 2 
2.2 d-tree scripts - Tutorial 


Now that we have seen how easy it is to generate a complete file maintenance 
program for the Customer Master File (as well as for the Project Master File), 

“-o let’s take a closer look at how "run" accomplished this. Bring back the 
“customer.dts" file in your editor. Right away you will notice that some changes 
have been made to the file. This was done by "run" to provide a complete 
default script for d-tree which implements the file maintenance process. 


A new first line has been inserted into the file. It looks something like this: 
IMAGE(master) {LSTFLD_ADVANCE} 


This line labels the screen image which we created. The default reference name 
which is given to our screen is "master'. The information contained in squiggly 
braces ("{}'") specifies options. For a thorough discussion of these options, see 
the Ability Reference Section. 


Next is our screen image. This has not been changed. However, following it are 
more new script entries. We will quickly look at them but for a detailed descrip- 
tion, see the d-tree Ability Reference Section. The next set of script lines looks 
like this: 


| es IFILS FILE NAME customer 
KEY NAME customeridx 
KEY FIELDS Fooo1 


These items describe the incremental file structures ("IFILS"). These names are 
the symbolic references which will be used within the script for the data file and 
associated indexes. The data file symbolic reference is "customer'. The actual 
file name is found on disk as “customer .dat". Similarly, the index file symbolic 
reference is "customeridx" while the disk file name is "customer.idx". As a 
default, "run" assumes that the first field specified is to be a "key’ field. It 
specifies this with the KEY_FIELDS keyword. The first field is given the default 
name of "F0001" (see next page). 


d-tree Reference Guide 2-11 


2.2 d-tree scripts - Tutorial 


The next section of script looks like: 


custorer.dts 
FIELD( master) 
“7 Symbol Nane Input Atribute Output Atribute Input Order Special */ 
FeGel NONE “7* Customer Id: »*/ 
FeGGZ NONE NONE Name: 7 
Feo83 NONE NONE Address: */ 
Feee4 NONE NONE City: 7 
State: */ 
Zip: ™/ 
Phone: 7 
Customer Type Code: */ 
Last Trans Date: */ 
Customer Balance: 7 


F@ees NONE NONE 
F@@86 NONE NONE 
FOGO7 NONE NONE 
FQ8e8 NONE NONE 
Fees NONE NONE 
F@G18 NONE NONE 


QBMWUONOAUAWN re 


~~ 


The "FIELD" keyword identifies this section which specifies: data fields used on 
the screen, special attributes for input or output of the field, the input sequence, 
and a comment which contains the label which preceded the data field on the 
screen. | 


Since multiple screens may be needed within the same d-tree script, each 
FIELD section is tied to a specific IMAGE section. This is done by the 
parameter which follows the "FIELD" keyword (in our case "master’). 


Each data field in our screen image is given a symbolic name. The default 
names begin with the letter "F" followed by a four digit sequence number. These 
names can be changed, as long as you're careful. Be sure that changes are 
made consistently throughout the script. One special task is also required to 
change these names. Changing the names in this FIELD section will define the 
symbolic names in the DODA (described later). In order for the field names 
defined in the IFILS structure to be valid the IFILS definition block must be 
moved below the FIELDS defininition block (note: this only pertains to the "run" 
program when field names are changed. This is not a general rule in d-tree. ) 


The next column contains Input Attributes. The default created for us by "run" 
is "NONE". These values can specify various character level edits, attributes, 
and formats for handling the input values. 


For example, if we wish to use alphas in the "Customer ID" field, it would be use- 
ful if the system would automatically shift any lower-case alphabetic characters 
to upper-case. This can be accomplished by replacing the "NONE" keyword 
under "Input Attributes" for "F0001" (Customer ID) with "ALLCAPS". The same 
could be done with the "State" field (F0006). Another useful function would be to 
capitalize only the first letters of each word in the "Name" field. This is specified 
by placing the "ALLWORDCAPS" keyword in the Input Attribute for field Fooo2. 
More specific character level editing can be done with field MASKS. These are 
defined as an additional attribute. 


0 ea earn nem ur Gaiman — sao yanianea=rL sa or oe 
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Try making these changes to your script. For more information on other Input 
Attributes, Output Attributes, and MASKS, please see the FIELD keyword 
definition in the Abilities Reference Section. 


Input Order defines the direction the cursor will travel when maintaining this 
image. The cursor simply travels from field to field in this order (ie: 1 is the first 
field, 2 is the second, etc.) The default order is top down, left to right. Try chang- 
ing the order and notice the cursor flow when the program is rerun. You will be 
asked to rerun the program after a few more steps. 


The next section of the d-tree script looks like this: 


customer.dts 


EDITS(C master) 


Must Enter Field F@@@1 MANDATORY 
This record Already Exists F@@@1 DUPKEY customer_idx 


This section provides "full field" editing of the values entered, as opposed to 
character level editing provided by the FIELD keyword. Again, since multiple 
sets of edits may be included in a single d-tree script, we specify which IMAGE 
these EDITS pertain to by specifying the reference "master". 


Two edits are provided with the default script which "run" generated. The first 
specifies that field FO001 is "MANDATORY". While in this field, if the user at- 
tempts to field exit without having entered information, the message 

"Must Enter Field" will be displayed in the error message area. 


The second edit specifies a check for duplicates ("DUPKEY") on field F0001. 
This is performed by checking the key index "customer_idx" for a match on the 
value entered for this field by the user. If a match is found, the key has already 
been assigned to an existing record and therefore cannot be added with this 
record. If a duplicate condition is detected, the message 

"This record Already Exists" appears in the error message area. 


For our application, let’s add an edit to mandatory fill the state field. (FO005). 
This is done by adding a new line to the EDITS section. The general format of 
this line is: 

Error Message——-——— FIELDID EDIT TYPE 
State Must Have Two Characters FOoOO0S MAND FILL 


Enter this line into your d-tree script right after the current DUPKEY edit. 


The remaining script sections contain additional specifications about how to 
handle: 

@ "browse" mode for retrieving records for update or deletion. 

e@ menu for selecting mode in which the program is to operate. 

e various other Abilities. 
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We shall discuss these in detail later in this session. Also, you may find each 
keyword in the Abilities Section of the d-tree Reference Manual. 


That's enough changes for now, let’s rerun our script and check the effect of the 
changes we've made. Exit your editor after saving the file. Then invoke the "run" 
program again as follows: 


C> run customer.dts 


When you get to the main menu, select the "Add Record" option. Try entering 
lower-case alpha characters as part of the "Customer ID" and "State" fields. 
Notice that the system automatically converts any input to upper case. Next 
enter only one character in the state field. An error message should appear 

- detecting this error. Notice cursor flow if you changed the order. 


In general, modifying d-tree scripts is that easy! With only a basic under- 
standing of the details of the script definition, you are able to customize a file 
maintenance program to your needs. Let’s take a quick look at the remainder of 
the default script generated by "run". Use "esc esc " to exit the File Main- 
tenance Program then reload the script file into your editor. 


The next section following our "EDITS" section is as follows: 


customer.dts 
IMAGEC heading) {LSTFLD_ADUANCE} {FRSFLD_BACKUP} 
@DATE Small Project Accounting System @TIME 
Customer Master Maintenance 
Select 


Enter Desired Option: __ 
Press ESC ESC to EXIT 
FairCom (c) 1988 


This screen IMAGE forms part of the screen which is used to show multiple 
records in browse or "SCAN" mode. It provides the heading portion of the 
Screen as well as the input area for the selected option. 


Note that the IMAGE is given a reference name ("heading") different from that 
of our first image (master'). This is necessary in order to uniquely identify each 
image within the script. As you might suspect, the "heading" image has an as- 
sociated "FIELD" specification. This is the next section in the script: 
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customer.dts 


FIELD( heading) 
7* Symbol Name Input Atribute Output Atribute Input Order Special */ 


option NONE NONE 1 


This section specifies only one field, named "option". The field "option" is a 
global variable used by d-tree. It is used to enter the selection number from 
the browse screen. 


The next section specifies another image which shows the format of the records 
which are shown within the "heading" image. This image looks like: 


custormer.dts 
IMAGECrollpart) {NO_CLS} {LSTFLD_ADVANCE} {FRSFLD_BACKUP?} 


Notice that the underscores specify the size and location of all of the fields in 
a record, just as with our screen image. Since "run" was not able to fit fields of 
the record on one line, it broke the record into four lines. We can, of course, 
edit this image to make it fit our needs. Care must be taken to reflect any 
changes to the IMAGE in the upcoming FIELD specifications. Let’s look at 
that first. 


customer.dts 
FIELD(C rollpart) 
7* Symbol Name Input Attribute Output Attribute Input Order 1/0 Mask */ 
counter NONE NONE 1 
FOGG1 NONE NONE 2 7* Customer Id: */ 
FQ@8G2 NONE NONE 74 Name: */ 
F8G63 NONE NONE 7* Address: */ 
7* City: */ 
7* State: 
ra | Zip: eS 
7% Phones */ 
7% Customer Type Code: / 
7* Last Transn Date: =/ 
7% Customer Balance: */ 


FQGG4 NONE NONE 
F@G@S NONE NONE 
FGGG6 NONE NONE 
FOGG7 NONE NONE 
Faaas NONE NONE 
FeQG39 NONE NONE 
F618 NONE NONE 


KMBOQwonoul bw 


a 


First note that this FIELD specification is tied to the IMAGE we just studied, by 
the reference name "rollpart". This specification shows eleven fields, one for 
each of the fields of our data record plus one for the "counter'. The field 
‘counter’ is another global work field provided by d-tree. 
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Now let's modify the "rollpart" IMAGE and FIELD specifications to show only the 
counter, the customer ID, name, and type. In other words, let’s drop all but 
what is essential to uniquely identify an individual customer so that we can fit 
the remaining fields on one line. 


We first use our editor to delete the underscores for the fields we wish to 
eliminate from our scroll-part. Then we move the underscores for the customer 
type field up to the same line. Next we must remember to delete the cor- 
responding line from the field specification. We should also renumber the Input 
Order entries. Once these changes have been made these sections should look 
like: 

customer. dts 
IMAGECrollpart) {NO_CLS} {LSTFLD_ADUANCE} {FRSFLD_BACKUP} 


FIELDCrollpart) 


7* Symbol Name Input Attribute Output Attribute Input Order I/O Mask */ 
counter NONE NONE 1 
FeeG1 NONE NONE 2 “* Customer Id: »*/ 
FBB8Z NONE NONE 3 7% Name: / 
Faces NONE NONE 4 /* Customer Type */ 


Let's continue our look at the remainder of the script before running it. The next 
section is shown here: 


customer.dts 
IMAGEC prompt) {INPUT_ADUANCE=1} 
@DATE Small Project Accounting System @TIME 
Customer Master Maintenance 


Enter Desired Record Key: 


Press ESC ESC to EXIT 
FairCom (c) 1988 


FIELDC( prompt ) 
7* Symbol Name Input Atribute Output Atribute Input Order Special M7 
Feoe1 NONE NONE 1 
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This section provides what is called the "prompt" for retrieving records. You 
probably remember the format from our use of the Change/View Records and 
the Delete Record options from the main menu. Notice again that the IMAGE 
and FIELD sections are tied together with the reference name "prompt". 


The "run" program defaults to the prompt phrase "Enter Desired Record Key:". 
As with much of d-tree, this may be changed to fit your specific needs. Why 
don’t we change this default to read "Enter Desired Customer ID:". 


The next section should also look familiar: 


seo sa custorer.dts 

IMAGEC menud {CLSTFLD_ADVANCE?} 

@DATE Small Project Accounting System @TINE 
Customer Master Maintenance 


Add Records 
Change“View Records 
Delete Record 

Print Records 


Pe 


Option: __ 


Press ESC ESC to EXIT 
FairCom (c) 1988 


FIELD( menu) 
7* Symbol Name Input Atribute Output Atribute Input Order Special */ 
option NONE NONE 1 


This section obviously describes the menu screen, complete with the "option" - 
which is selected. The default wording used for the menu selections may also 
be modified. Change the option descriptions to read: 


1. Add New Customers 

2. View/Update Customers 
3. Remove Customers 

4. List Customers 
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The final sections are a little less obvious. First: 


custorer.dts 
ua CIMAGE_OUT=heading}? {IMAGE_ROL=roll part} CIMAGE_INP=heading} | 


This script entry controls the browse mode for retrieving records. The "SCAN" 
keyword sets this up. The "SCAN" reference name, defaulted to "master', is Ne 
used to identify this "SCAN" to the "PROMPT" section below. 


The "SCAN" syntax specifies both a fixed screen portion 
(“IMAGE_OUT = heading") and a scrolling portion ("IMAGE_ROL=rollpart’). It 
also describes which IMAGE is to be used for input ("IMAGE_INP = heading’). 
In each case, the symbolic reference is used to tie the various components 
together. 


The last section in the default script controls the retrieval process. This 
"PROMPT’ is identified as "master’. The IMAGE to be used for prompting is 
specified with the "USES IMAGE" keyword. In our case, the IMAGE labeled 
"prompt will be used to request a value for the retrieval key. The key ("cus- 
tomer_idx") to be searched (if “fields for target" match) is specified followed by 
the name of the scan routine ("master’) to be used if an exact match on the key 
is not found. Finally, the field(s) which relates to the search is specified as 
"F0001". This is the field (must be defined in the "USES IMAGE" image) that is 
used to determine if this is the proper key and scan to use. As you will see later 
most prompts have more that one key and scan alternative. If values have been ~ 
entered into the "fields for target" field(s) (in this case just one-F0001) then this 
index and scan will be used. The PROMPT keyword has some powerful 
methods for building targets to access data. See the Abilities Reference Section 
for complete details. 


customer.dts 
PROMPT( master) 
USES_IMAGEC prompt ) 


7* key symbol name = scann name fields for target prefix »/ 
customer_idx master FG@GG1 


We made some further changes since we last used "run" with our modified 
script, so save the changes, exit your editor and rerun the script to check out | 
the changes made to the retrieval screens. Ss 
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Review 


In this session, we have looked at some details of how "run" uses the d-tree 
script to quickly implement a file maintenance function. We saw that by making 
easy modifications to the script we are able to customize the "run" program to 
meet our needs. 


Exercise (this exercise is optional to complete tutorial) 


Modify the d-tree script which you generated for Project Master File Main- 
tenance. Include the following changes: 


a) for the Project Code field, force alpha characters to upper case. (ALLCAPS) 


b) for the Contact field, add a new input attribute which specifies the automatic 
capitalization of the first letters of each word. This is done by replacing the 
NONE input attribute with ALLWORDCAPS. 


c) for the YTD Expenses and YTD Income fields, specify an input attribute of 
NUMERIC. 


d) for the Project Type field, add a “TABLE” edit. 

The "TABLE" edit format is: 

Error Message FIELD SYMBOL TABLE value value2 ... 
Example: 

Project Type must be ’BIL’ or ’NON’ F0002 TABLE BIL NON 


e) for the Start Date and End Date fields, add a MMDDYY date edit to the edits 
section. 


Example: 
Invalid Date FOO05 DATE MMDDYY 
Invalid Date FOO06 DATE MMDDYY 
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2.3 The Catalog - Tutorial 


The "run" program was intended as an example mainline, providing a fast 
method to complete a simple application. It is useful for prototyping, develop- 
ment and maintenance (when you need some test data in a file fast, or you 
need fast maintenance to fix a flag in a file, etc). It’s primary purpose is to illus- 
tate the dynamics that are possible using the tools. Later sections will go into 
the tools that were used in "run". That’s where the true power of d-tree lies. 


d-tree provides several ways to perform file maintenance. In this session, we are 
going to work with another application written with the tools called the catalog. 
The d-tree catalog provides a consistent way of maintaining detailed information 
about our applications. There are several sections to the catalog: the data dic- 
tionary, the program dictionary, and the relate dictionary are the most evident. 
(For details on these and other features of the catalog, see the Catalog Section 
of the d-tree Reference Manual.) 


One of the useful things that the d-tree catalog does is to automatically create 
program specifications not only for simple single-file maintenance programs, but 
also involving multiple- file update programs. This saves the programmer a lot of 
detail work. In our exercises we will create programs using several files. Some 
will be used to validate fields and others as subfiles or update files. In order for 
the catalog program to do this, all files must first be defined in the data diction- 


ary. 


The catalog provides the capability to import file definitions based on d-tree 
scripts which may have been created by the "run" program. Let's see how this 
is done as well as look at some of the features of the catalog itself. 


Before starting the catalog, be sure that your TERM environment variable is 
properly set as described is Session 1. Also be sure you have imported the 
validation data into the dt_catvd files as described in the installation guide. 


To activate the catalog from the system prompt, enter: 
C> dtcatlog 


It will take a little time for the catalog to finish loading. The reason for this is that 
the catalog will parse in its ALIBITY definitions from a d-tree script. 


After the first run, the catalog will load much faster since it has stored the results 
of the parsing into the dictionary itself. You might find it interesting to analyze 
the catalog script which is in the file "DTCATLOG.DTS". 


d-tree Reference Guide 2-21 


2.3 The Catalog - Tutorial 
The catalog will display the main menu screen as shown below: 


Sat Apr 28 FairCom 87:37:28 
System Catalog 


aster Menu 
Data Dictionary 
Relate Dictionary 
Execute Compile Que 


Clear Compile Que 
Catalog Reports 
Return to OS 


FairConm (c) 1988 


For the demonstration of importing our "run"-generated scripts, select the 
"Program Dictionary" selection from the main menu. At this point, a secondary 
menu will "pop-up" which looks like this: 


Sat Apr 28 FairConm 67:37:28 
System Catalog 


aster Menu 
Data Dictionary 
Program Dictionary 
Relate Dictionary 
Execute Compile Que 


Clear Compile Que 


Catalog Reports Import Pgm 


Return to OS 


FairCom (c) 1988 


For now, select the "Import Pgm" option from the secondary menu. This will 
prompt you for the d-tree script name. First, import the "customer" script (do 

not enter extension..the default of .dts will be used). When everything has been 
added to the dictionary, the catalog program will parse in the script created by 
the "run" program and begin executing your program from within the catalog 
environment . An interesting thing has just happened which illustrates one of the 
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most powerful aspects of the d-tree tools. Applying the tools in the proper man- 
ner allows the user to create data independent mainline programs where the 
data file as well as the ABILITY definitions can be swapped in and out of 
memory. We have just freed the catalog definition and loaded in the customer 
definition. The program now executes exactly like the "run" program, but you 
are actually in the catalog mainline. Exit the customer maintenance with "esc 
esc". The customer definition will be freed, and the catalog definition will be 
reloaded from the dictionary, returning you to the main menu of the catalog. 


Now let’s look into the "Data Dictionary’ to see what was imported. Select "Data 
Dictionary" from the main menu and "View/Modify" from the secondary menu. 
You will next be asked for a file name to work with. You may specify the exact 
file name or, if you aren't sure, enter "0". (Remember the browse mode in our 
SPA maintenance programs?) This will provide you with a list of files for which 
data dictionary entries are currently maintained. Simply select the number in 
front of the "customer' file name. 


The next screen you see should look like this: 


Apr 26 airlo 

File Name: (customer ] File Description: customer 
Version Number: 1 System Name: IMPORTED 
File Type: Extension: - 4896 Mode: 1 Rcd Len: 162 Indexes: 1 

Field Field First Vlen 
Name Type Len Dec Description Field 

FOOG1 re) ii Customer Id: 

F882 41 Name: 

FGGG3 41 Address: 

FGG84 Z1 City: 

FQGGGS State: 

FQGG6 Zip: 

FOGG7 Phone: 

FGGa8 Customer Type Code: 

FQ6e9 Last Transaction Date: 

FG0190 Customer Balance: 


11 
15 


A 
A 
A 
A 
A 
A 
A 
A 
DF 


ae 
ioe 
Boe 


Press ESC ESC to EXIT 


Notice that the catalog has made entries into the data dictionary. Entries have 
also been made to the program dictionary. In addition, d-tree records the rela- 
tions between data and program in the relation dictionary. The catalog has pick- 
ed up a complete description of our application and its data. With the reports 
available from the catalog, this provides excellent documentation and control 
over data specifications. 
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Once both program and data dictionary entries have been made in the catalog, 

d-tree can help maintain and control changes. One way d-tree can do this is by 
identifying where a specific field (or file or index, etc.) is referenced. This allows 

for easier estimation of the magnitude of a change as well as expediting the ac- 
tual implementation of the change. For more details, see the Reference Manual 

section on the catalog and its reporting functions. 


But that’s not all! Let’s assume that we need to change a field size in an existing 
data file. Before d-tree, this would involve many hours of recoding, writing spe- 
cial conversion programs, testing everything, then finally switching over. With d- 
tree this type of change is handled with minimal effort. 


The catalog provides more direct assistance for these maintenance situations. 
Since we are in the Data Dictionary with our "customer' file in browse/modify 
mode, let's change the size of the Customer Type field. It is currently 3 charac- 
ters long. Let’s assume that we need to make it 6 characters long. First though, 
notice that the lengths indicated on the data dictionary screen are one greater 
than what we specified for "run". This is due to the need for string lengths to in- 
clude space for a null byte to terminate the string in the " C" language. We must 
remember to add this extra character to the length of any strings when enter- 
Ing field definitions from the data dictionary. 


Simply use the arrow keys to position yourself at the length field for FOO08. Then 
change the length entry from 4 to 7. Now use the POST key (for IBM-PC use 
the END key - or see termcap for proper key) to accept the change. 


When you are in modify mode in the data dictionary and make any change to 
the file definition, the catalog will know it. If any change has been made, the 
catalog asks if this is a new version (with its own version number) or a replace- 
ment for the same version number. If you specify (N)ew, you must have already 
changed the version number. If you have not, the catalog will display the follow- 
ing error message: 


New Version of File Definition Must Have New Name Or Version Number 


and return you to the main file description screen. If, in fact, you want a new ver- 
sion, change the version number (for example, to 1.1) and use the POST key 
again. 


For our example, specify (R)eplace. With this option you will be given a chance 
to reformat the file from the old format to the new format. The catalog also gives 
you the option of creating a stand-alone executable program that can be used 
for converting files from the old format to the new format at any time. This 
provides a package that you can supply to your customers to automatically up- 
date their files. These options are presented with the following screen: 
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Sat Apr 28 FairConm G8: 15: 42 
File Reformatting Utility 


The Old File Definition is Will Be REPLACED. 


The file format facility requires both the old and the new file 
layouts. If you want to take advantage of the file reformat 
facility one of the following actions must be selected: 


C_JReformat the following file in place. 


_ Create a stand alone executable to be used for 
reformatting at a later tine. 


Place a ‘Y° in desired option(s) then 
Hit POST key to continue. 


FairCom (c) 1988 
Press ESC ESC to CANCEL REPLACE 


Since the old file format is lost forever, if you do not choose one of these op- 
tions, automatic reformatting will be difficult. In fact, you will probably need to 
rekey the old file format into the catalog. (NOTE: both options may be selected) 


Because we are in an exercise, let it reformat the file in place by placing a ’Y’ in 
the first option. You will next see the following screen which shows the mapping 
of the old format into the new format: 


pr 
File Name: customer File Description: customer 
Version Number: 1 System Name: IMPORTED 
File Type: Extension: 4896 Mode: 1 Red Len: 164 Indexes: 


mxmMmMMMOM Old File Layout rma i Hamme New File Layout >a 
Map Typ Len Off Var’ | Map Typ Len Off Var 
Bs iz 8 a 1. ia &4 8 

12 11 12 41 11 
12 4 i2 41 S2 
12 33 iz @2i $3 
12 114 5 3 114 
12 117 a. 32 2i7 
1Z 128 iZ.. 45 ize 
LZ 143 12 6 143 
12 147 12 7 149 
8 154 8 8 156 


@®oooooadod ®& © 
OQooooodao ® & 


ies 
Fe 
4. 
i 
6. 
ie 
8. 
ax 
8. 


aero rere 


rs 
~~ 


Press RETURN to START RE-FORMAT 
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Pressing 'RETURN’ will execute an in-place file reformat. You will see the mes- 
sages that the reformat as well as the index rebuild is in process. Those of you 
who have used c-tree’s rebuild facility will recognize these messages. The file 
reformat has NULL'd out the header portion of the c-tree file. The rebuild will 
reconstruct the entire header. Because the header has been NULL’d out the fol- 
lowing message may appear. Simply answer yes (Y) to the prompt for the 
rebuild to continue.(note: you must respond with a yes. Failure may result in 
a divide by zero run time error. 


WARNING: data record length discrepancy. 
Parameter file data record length = 161 
Header data record length = @ 


Use parameter file value? Cy or n)>> y 

WARNING: file extension size discrepancy. 

Parameter file file extension size = 4896 
Header file extension size = 6 


Use parameter file value? (y or n)>> y 


The catalog rebuilds files by calling c-tree’s RBLIFIL function. It is this function 
that is displaying these messages. These messages can be suppressed by edit- 
ing the c-tree file ctrbl2.c and setting the proper #define’s. The following is a 
snap shot of this c-tree source file. 


ctrblZ.c 
1 
“ To disable interactive rebuild prompts and/or to suppress normal 
* rebuild output, “comment out’ one or both of the follouing 
™« defines: 
u/s 


tdefine RB_INTERACTIVE 
tdefine RB_OUTPUT 


Note: Something to keep in mind later as you work with d-tree. You will be creat- 
ing many d-tree scripts for different programs as you develop with d-tree. If you 
modify to a file structure, such as changing a field length, you will need to go 
back into the scripts which contain a reference to this field, and make the neces- 
- Sary changes (i.e. change input length of the field on the screen). 


3%0.000070-—-—-—-———— 
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Let’s create another file specification, but this time we will use "dtcatlog" instead 
of "run". We need a file maintenance program for the Vendor Master File. 


This file should contain: 


e Vendor Code 10 positions 

e Vendor Balance 8.2 format for money 

e Vendor Name 40 positions (first vlen field) 
e Vendor Address (2 lines) 40 positions each 

e Vendor City 20 positions 

e Vendor State 2 position 

e Vendor ZIP Code 10 positions 

e Vendor Type Code 4 positions 


Enter the catalog program and select "Data Dictionary" from the main menu. 
Then choose "Add" mode. The following screen will then appear: 


[ Sat Apr Zé airCom 
File Name: ( ] File Description: 
Version Number: System Name: 
File Type: Extension: Mode: __ Rcd Len: Indexes: —___ 
Field Field First Vlen 
Name Len Dec Description Field 


Type 


Press ESC ESC to EXIT 


Assign the file name of “vendor'. Enter an appropriate Description, such as 
"Vendor Master File Maintenance". The version should be "1" or "1.0". The sys- 
tem name is "Small Project Acctng". File type is "MASTER". The extension 
specifies the file size extension of the data file (c-tree). For now, hit the default 
key (TAB key). 
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The mode specifies the c-tree file modes for operation, such as VIRTUAL, 
SHARED, etc. This is a good place to look at d-tree’s lookup (SCAN) features. 
Use the lookup key (?) while in the mode field on the screen. This will provide a 
list of valid file modes which looks something like this: 


a pr 


@airlom 

Valid Codes 
(FIXED VIRTUAL SHARED) 
(FIXED PERMANENT EXCLUSIVE) 
CFIXED PERMANENT SHARED) 
CULENGTH VIRTUAL EXCLUSIVE) 
C ULENGTH UIRTUAL SHARED) 
(C ULENGTH PERMANENT EXCLUSIVE) 
( ULENGTH PERMANENT SHARED) 


Enter Desired Option:(€_ J 
FairCom (c) 1988 
Press ESC ESC to EXIT 


This list provides all valid alternatives for the c-tree file modes. Components in- 
clude: fixed versus variable length, permanent versus virtual, and shared versus 
exclusive. Simply select the combination you desire (in this case 5). 


Back on the File Description screen, the size of each field along with alignment 
requirements will supply the record length. The catalog will count the number of 
Indexes when information is posted, therefore these fields are protected. 


Next, we can specify fields within the record. For each field, we can supply: 
e the field name 
e the field type 
e the length of the field 
@ the number of decimal digits (for real or floating values) 
e a description 
e an indication of the first variable length field (if applicable) 


Supply this fleld information from the specifications given above for the Vendor 
Master file. Let's make this a variable length file. The vendor code and balance 
will be in the fixed length portion of the file, and the rest is considered variable. 
To make this a variable length file simply key a "VL" in the "First Vien Field" 
position for the first variable length field, in this case vendor name. 
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When you are done, your screen should look something like this: 


P 
File Name: (vendor J File Description: Vendor Master File 


Version Number: 1.8 System Name: Small Project Acct. 
File Type: MASTER Extension: 4696 Mode: 5S Rcd Len: _. Indexes: ____ 
Field First Vlen 
Type Dec Description Field 
A Vendor Code 
DF Vendor Balance 
Vendor Name 
Vendor Address 1 
Vendor Address 2 
Vendor City 
Vendor State 
Vendor Zip 
Vendor Type 


NI 


und_addrl 
vnd_addrZ 
vnd_city 


vnd_state 
vnd_zip 
vnd_type 


Paha he ee ee ee 


Ce aR tal 


Press ESC ESC to EXIT 


Now we can define the index structure by using the (F3) key. Pressing will dis- 
play this screen: 


P 
File Name: vendor File Description: Vendor Master File 
Version Number: 1.8 System Name: Small Project Acct. 
File Type: MASTER Extension: 4896 Mode: S Red Len: Indexes: 


Key Definitions 


Key Key Dups Null’ Empty Index File 
Length Type Ok Key Char Mode Ext Name 
N N 


] 


Field Name Offset Length Mode 


ESC ESC to EXIT 


Enter a key name of "vnd_code _ idx". You can use the DEFAULT key to move 
through the items until you reach the Field Name. Enter "vnd_code" to set the 
vendor code as the primary key. The offset is 0, the length 10, with mode of 0. 
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CAUTION: Developers who have worked with c-tree are use to entering the of- 
fset of a field as it pertains to the record structure. In d-tree, however, the 
catalog knows at what offset a field begins in relation to the record structure, 
without you telling it. Therfore, this offset is NOT what you are used to thinking 
of in c-tree. This is the offset within the field to start this key segment. Ex- 
ample: Let's say you had a date field that was a six byte string in the form 
MMDDYY and you wanted to build an index using this field. The first segment 
would have the date field name with an offset of 4 with a length of 2(selecting 
the YY), followed by a second segment with the same date field name with of- 
fset of 0 and length 4(selecting MMDD). Again, THIS IS THE OFFSET WITHIN 
THE FIELD, NOT THE OFFSET WITHIN THE RECORD STRUCTURE. After all 
key definition information is entered, use the POST key (END for DOS) to com- 
plete the entry. This will then return you to a blank File Definition screen. We are 
still in ADD mode so let's enter the last three file descriptions into the catalog. 


Enter file file definitions for the following files: 
e Account Code File. 
e Transaction File. 
e Distribution File. 


Use the relationship chart below for field sizes. Be sure to set up the key struc- 
ture for at least a key on the first field of each of these files before posting the 
file description. If you forgot, go back into View/Modify mode for each file and 
do it then. Note: The index for the "dist" file should support duplicates so many 
records related to a single "trans" record may be entered. 


custorer vendor 
Customer ID: 11 State: 3 Code 11 Vendor State 
Name: 41 ZIP: 11 Bal 8,2 Vendor ZIP 
Address 1: 41 Phone: 1S Name 41 Vendor Type 
Address 2: 41 Type: 7 Addr 41 
City: 21 Last Date: 7 Addr 41 
Balance: 8,2 City Cvlen file) 


dist 
Transaction Reference 11 Distribution Account Code 6 
Distribution Amount 8.2 Distribution Project 6 | 


~—————————- 


project account 
Project Code 6 Start Date Code 6 
Project Type 4 End Date Description 41 
Description -41 YTD Expenses i Category = 
Contact 21 YTD Income > Balance 8,2 


San 
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Once we have our file definitions in the catalog, we have a number of helpful 
and powerful functions available to us. Let’s take a quick look at some of these. 


Now enter the Data Dictionary in View/Modify mode. Select the Vendor file. 


As seen earlier, Pressing Function Key 3 (F3) will display the index definition. In 
order to return to the File Description screen, simply press Function Key 8 (F8). 


Other functions that we can activate from the File Description screen include: 


e C record structure creation (F1) 


e DODA structure creation (F2) 
e Parameter file creation (F4) 
e Incremental structure creation (F5) 
e Instant file maintenance (F6) 


Short examples of each of these follow. 


F1 KEY- Creating C Record Structures: If we would like to generate a C 
record structure, simply press the (F1) key. The following screen should appear: 


Ap P4 
File Name: (vendor ] File Description: Vendor Master File 
Version Number: 1.6 System Name: Small Project Acct. 
File Type: MASTER Extension: 4896 Mode: S Rcd Len: 28 Indexes: 


7“ C Record Structure */ 

struct UC@ { 

TEXT vnd_codel11]; Vendor Code */ 
double vnd_bal; Vendor Balance */ 
TEXT vnd_namel[ 41]; Vendor Name */ 

TEXT vnd_addril 41]; Vendor Address 1 */ 
TEXT vnd_addr2( 41]; Vendor Address Z */“ 


TEXT vnd_city(21]: Vendor City */ 
TEXT vnd_statel3]; ; Vendor State */ 
TEXT vnd_zip(l111]; Vendor Zip */ 
TEXT vnd_typel(S]; Vendor Type *“% 
+ ucO@(3I; 


Press ESC ESC to EXIT 
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Pressing the (F1) key a second time will allow you to dump this structure to a 
disk file. d-tree will request the name of the source file to which you want the 
specification written. You will also be asked if you wish to append these 
specifications to an already existing source file. If you respond "N", any current 
contents of the filename specified are overwritten with these specifications. Try 
this. This is a quick way to save you some keying when creating programs, al- 
though there are better ways, as you will soon see. 


F2 - Create DODA Specs: Next, we can generate the DODA structure by press- 
ing (F2). Those of you who are using r-tree are already familiar with the data ob- 
ject definition array (DODA). d-tree uses the same concept. The DODA is the 
table used to assign symbolic names to fields in order to use the fields ina 
script interface. See DODA section in the d-tree reference manual for a com- 
plete definition of the DODA. The (F2) key will produce the DODA definitions. 
Once again, pressing (F2) a second time will activate the dump to disk option. 
The same procedure is followed as before, supplying the source file name and 
whether to append or overwrite the file. The following screen shows how your 
screen will look after the second (F2) has been hit. 


Pp : 
| File Name: (vendor J File Description: Vendor Master File 
Version Number: 1.8 System Name: Small Project Acct. 
File Type: MASTER Extension: 4896 Mode: . S Red Len: 28 Indexes: 


7* DODA Array */ 

DATOBJ DTSDDODACI = { 

“und_code” » NULL. RTSTRING ,11}, 7™ Vendor Code */ 
“und_bal” » NULL. RTDFLOAT , sizeof(double) },/7™ Vendor Balance */ 
"und_name™ » NULL, RTSTRING , 41}, 7* Vendor Name / 
“und_addri” » NULL, RTSTRING , 41}, 7* Vendor Address 1 */ 
“und_addr2” » NULL. RTSTRING , 41}, 7“ Vendor Address Z */ 
"und_city” , NULL, RTSTRING , 21}, 7™ Vendor City »/ 
‘und_state” » NULL. RTSTRING , 3}. “7% Vendor State */ 

“4 » NULL, RTSTRING ,11}. “7* Uendor Zip ™*/ 

» NULL, RTSTRING , 5S}, 7% Vendor Type */ 


{ 
{ 
C 
{ 
{ 
{‘ 
C 
is 
<" 
{ 


Press ESC ESC to EXIT 


F3 - Maintain Index Definitions: The (F3) key has already been demonstrated. 
It takes us to the Key Definition screen. 
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F4 - Create Parameter File(optional maint pgm): Moving on to the (F4) key, 
we can generate the parameter file specifications based upon our Data and Key 
Definitions for this file. Hit the (F4) key. The Parameter file will be displayed. 
Pressing the (F4) key again will provide the option to write a parameter file to 
disk and ,optionally, create a parameter type maintenance program. Because 
we have not created a maintenance program for the vendor file yet, let's hit the 
(F4) key a second time. The following screen appears: 


File Name: vendor File Description: Vendor Master File 
Version Number: 1.0 System Name: Small Project Acct. 
File Type: MASTER Extension: 4696 Mode: 5 Red Len: 2B Indexes: 


7* Parameter File */ 
18142 <- Initialzation 
@ dummy.dat 128 @ 3 @ dummyl dummyZ <«— Dummy Lock File 
1 vendor.dat 2@ 4696 S 1 vund_code vnd_type <—- Data File 
Z vendor.idx 11 @ @ @ 4096 1 1 32 1 ven_code_idx ‘- Index File 
@ ii a <—- Key Segment 


Dump Specs to Disk 
This option will dump the file specifications you are vieuing to disk. 
Key in the source file name of your choice WITHOUT an extention. 
The file name extension will default. A “.p” extention is used when 
viewing parameter files. A “.h” extention is used for incremental 


structures. A “Y’ for the create option results in an additional “.c” 
source file to be created for a standard maintenance program. 


Name of Source File(s): vendor__ Do you want to Create Program Source:(CY_] 


Give your source file the name "vendor", then create program source by 
responding with a yes ('Y"). A file named "vendor.p" will be created with or 
without the ("Y") response. With the ("Y") a program source file (‘Vendor.c'), a 
header file for the DODA definition (Vendor.h") as well as a d-tree script file 
(‘vendor.dts") will be created. 
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The program to be produced will be entered into the program dictionary using 
the the program dictionary entry screen as shown below. Enter your vendor 
program into the program dictionary using this screen as a guide: 


a 
Program Dictionary 


Add or Update Program to Code Dictionary 


program name: 

program version: ae 

program system name: Small Project Accounting _ 

program description: Vendor Master File Maintenance Program_ 
program type: std maint 


Press ESC ESC to EXIT 
Program Specs Now Written. Do you want to Submit to Compile Que7.CY_J 


Once the posting is complete, d-tree generates the various specification files. 
Once these are written to disk, you are asked if you wish to submit the program 
to the compile queue. The Compile Que is a time saving device that allows you 
to submit progams which need to be compiled to a single list. The compiles 
can then be initiated all at one time from the Master Menu screen. More on this 
a little later. Respond yes ("Y") to this prompt. You will be ask to press return 
once the program has been submitted to the compile queue, which will the 
return you to the main menu. 


F5 - Create Incremental File Structures (optional maint program): As with 
the (F4) option, the F5 option will allow for the creation of a maintenece file 
program. Lets pick another file for which we have no maintenece program yet. 
Go into the Change/View Mode of the data dictionary and select the ACCOUNT 
file. When viewing the account file definition press the (F5) key. the following 
screen will appear. 
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- A airCom 
File Name: Caccount J File Description: Account Code File 
Version Number: 1.8 System Name: Small Project Acct. 
| File Type: MASTER Extension: 4696 Mode: 1 Red Len: 58 Indexes: 1 


ISEG DTSISEGS(C] = { “* ISEGS 7 
{ @, 6, @ ee 
+; 


IIDX DTSIIDXSCI = € 7* TIDXS 7 
C 


» “*key length*/ 

. “*key typex’ 

. “duplicate flag*/ 

» 7¥null key Flag*/ 
32, “empty character*/ 

» “*number of segments’ 
DTSISEGS+@, “segment infox/ 
“act_code_idx” /*r-tree symbolic name/ 


rs 
Press ESC ESC to EXIT 


Use the rollup and rolldown keys to see entire structures. Follow the same pro- 
cedures as described for the parameter file program to create a maintenance 
program that uses incremental structures, by pressing (F5) a second time. Enter 
a source file name of "account". Everthing will process as before, creating the 
appropriate source files. The difference is that there will be no parameter ('.p") 
file and the header ('.h") file will contain the incremental structures along with 
the DODA definiton. The #define in the mainline (".c") file for parameter files will 
not be included. (compare the source files for "vendor.*" to the "account.*" to 
see difference between parameter file maintenance programs and incremental 
file programs). 


Now what about this compile queue? To understand this in detail, return to the 
operating system prompt and look at the contents of the file "DTCOMPIL.QUE". 
(this can be done with the "type" or "cat" command).This file contains the names 
of the programs ready to be compiled. During the installation of d-tree, a batch 
file called "DTQUE.BAT" was configured. When executed, this file calls the 
program "DT_DOQUE" which in turn reads each entry from "DTCOMPILE.QUE". 
It the submits each program name to the batch file that compiles the program 
(DTCOMPIL.BAT). Look at these files to understand the flow. Return to the 
Catalog’s main menu and select the option to "Execute the Compile Que". This 
will compile the two programs you created ("vendor' and “account") by calling 
DT DOQUE. 


PE en A SO ae A De PE a EO eT OR ES SEEN Tae aN, TOY 
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F6 - Instant File Maintenance: One of the most useful options within the 
catalog is the ability to do instant maintenance over any file defined in the data 
dictionary. How many times have you wished you had a "quick and dirty’ way to 
do raw maintenance for all data elements of a file (either to fix a corrupted flag, 
or add test data during development) without wasting valuable time. Go back 
into the data dictionary and select the account file. While viewing the file 
definiton hit (F6). The catalog will create a default script (much like the "run" 
program did) and begin executing its definiton. Add some records to the ac- 
count file with option 1 and then View them with option 2. Escaping out will 
return you to the catalog. (Note: you never left the catalogs executable mainline. 
This is another example of using the powerful tools within d-tree to create data 
independent mainlines. When (F6) was selected, the catalog’s definiton was 
freed from memory and the project definiton was parsed into memory. The 
same mainline processed the project file. When we escaped back out of project 
maintenance, its definition was freed from memory and the catalog definiton 
was re-loaded from the ability dictionary.) 


F7 - Not Used 


F8- Return to Definition Maintenance: This will return you to the primary file 
definition screen when viewing any other screen provoke by the function keys. 


F9 - Delete line in subfile. 
F10 - Insert line in subfile. 


EXERCISE: (must be done to complete file definitons) 

We now have all files, except one, in the data dictionary. The project file 
definiton we created with "run" has not yet been brought into the catalog. 
Return to the program dictionary and import the project definiton in the same 
manner as the customer definiton. (See start of this session.) After importing the 
project files into the Data Dictionary, it will be necessary to modify the field 
names in order to to distingush them from the fields that where defined in the 
customer file. (/f you recall, the customer master file that was imported also 
uses the symbolic identifiers F0001, FO002, FO003...) Following sessions will 
create a DODA with both files defined. Non-unique names will cause the same 
symbolic field names for two different fields. 


FO 
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2.4 Muti-File Program - Tutorial 


Let’s explore some other capabilities of the catalog. Now that each of our files 
are defined, we can create a Multiple-File File Maintenance Program. This would 
allow validating information across files, having subfiles of information related to 
a master file, and performing updates directly to related files. 


In the Data Dictionary, choose the "Select File" option. The catalog then re- 
quests which source specs to create by displaying a screen like this: 


des sell 1rlom 5: U7: 46 
System Catalog 
Select of Group of Files 


Select the Desired Source Specs to Create 


C ] Create a Parameter File 
Create C Source Structures 
Create a Data Object Def Array (DODA) 
Create Incremental Structures 
Create a d-tree Script 
Create a r-tree Script 


Enter Source File Name: 


Do you want to make an entry into the Program Dictionary: __ 


FairCom (c) 1988 
Press ESC ESC to EXIT 


This screen allows you to specify which program components you wish to have 
d-tree generate for you. d-tree needs only the DODA, the Incremental Struc- 
tures and the d-tree script. The parameter file, C source structures, and the r- 
tree script are optional. You select the specs you want by placing a "Y" in front 
of them. At the prompt for the Source File Name, enter the name you wish to 
call your new program (no extension). Next you are asked if you wish to enter 
this into the Program Dictionary. This will cause d-tree to create a ".c" mainline 
file as well as prompt for an entry into the Program Dictionary. 


For our example, let’s specify that we want all available source specs (remem- 
ber, A Parameter File and Incremental Structures are really mutually exclusive, 
so select one or the other). Provide a Source File Name of "posting", for 'Trans- 
action Posting Program", and specify that d-tree should enter the specs into the 
Program Dictionary. 
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d-tree then allows us to specify which of our files in the data dictionary are to 
be included in our Multi-File program. It asks for either a file name, file descrip- 
tion or file system. This is the same "PROMPT" that you see in the View/Modify 
Mode. It is easiest to respond to "PROMPT" screen with "0" to specify a scan of 
all files in the data dictionary. 


The scan should list our files like this: 


Data Dictionary 
Name Version Description System 
account Account Code File Small Project Ac 
customer custorer IMPORTED 
dist Distribution File Small Project Ac 
trans 
vendor 


1 
1 
1. 
pro ject 5 pro ject IMPORTED 
1. Transaction Master File Small Project Ac 
1 Vendor Master File Small Project Ac 


FairCom (c) 1988 
Press ESC ESC to EXIT 


The "Sel" column allows us to not only select which files we wish to include but 
also which order they will reside in the source code that is created (ie: place- 
ment in paramter file, incremental files, doda and scripts). We do this by enter- 
ing a'"1" for the first file we wish to use. This is normally the master file for this 
update. We select the next file as "2" and so on. At the same time, we need to 
change the"File Type" column. The file type is used to determine the kind of 
entries that will be created in the d-tree script. In other words how this file is 
going to be used in this program. 


The following are valid entries for the type field: 


@ "MASTER" - Primary file that is to be maintained. Only one file that is 
selected should be designated as the master file. 


e "SFL" - A subfile is a related group of records. A subfile is most 
commonly used in a one-to-many maintenance situation. (ie: an invoice 
master record with numerous line item detail records. These detail 
records would be maintained in a subfile.) . 


DU 
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e "VAL" - Validation File. This file will be used to validate entries in the 
files that are being maintained. This file will be used as a "lookup" file 
allowing the user to scan thru this file, and select entries. (ie: When 
entering an invoice, the invoice record may require the customer 
number. The customer master file would then be defined as a "VAL" 
type file. This would allow validation of the customer number when it is 
keyed into the invoice, as well as allow a "lookup" into the customer 
master file for the user to select the proper customer.) Defining a file as 
a "VAL" type will cause script entries for the following: VALIDATE EDIT , 
SCAN and MAP. 


Let’s specify the Transaction File as our master file and the Distribution File as a 
subfile. Specify the Vendor File, the Customer File, the Account Code File, and 
the Project File for validation. Your screen should look like this: 


Dictionary 
Sel File Type Name Description System 
S VAL account . Account Code File Small Project Ac 
| C4]VAL customer , customer IMPORTED 
+ 2£ SFL dist ; Distribution File Small Project Ac 
6& VAL pro ject : project IMPORTED 
1 MASTER trans ; Transaction Master File Small Project Ac 
3 VAL vendor ‘ Vendor Master File Small Project Ac 


FairCom (c) 1988 
Press ESC ESC to EXIT 


Hit POST Key when Ready. 
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race ge gE a a 
After the source specs are created the screen will prompt to the program diction- 
ary entry: Enter data as shown on the following screen and submit this program 
to the compile queue. 


Program Dictionary 


Add or Update Program to Code Dictionary 


program name: posting 

program version: eS 

program system name: Small Project Accounting __ 
program description: Transaction Primary Posting Program 
program type: MAINT 


Press ESC ESC to EXIT 
Program Specs Now Uritten. Do you want to Submit to Compile Que7?.CY_] 


Now look at the specifications which we have generated: 


e "posting.c" - program mainline. 
e "posting.h"  - program header (c structures, doda, incremental 
structures). 


e "posting.dts" - d-tree script. 

e "posting.rts" - r-tree script. 

e "posting.p" - parameter file. (optional: only if parameter files were 
selected). 


Return to the operating system prompt, and using your editor we will look at the 
files that were created. (Press "ESC ESC" to back out of the catalog). 


"posting.c" - The ".c" file is very simple: 


posting.c 
tinclude “DT_DEFIN.H" 
Rinclude “posting. h" 
“define DT_DTS “posting. dts” 
tdefine DT_RTREE 


tdefine MYIFIL 1 
tdefine SFL 
#include ‘“DT_SCORE.c” 


YT), rr ween —oe Seen wer ori 
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This is the mainline for our program. It includes necessary header files (includ- 
ing "posting.h"). It then defines the script file (#define DT_DTS “posting.dts’). 
Optionally you would also see a #define statement for the parameter file if it 
was selected. It finally includes "dt_score.c". This is d-tree’s standard mainline 
(also used by "run" program). The #define SFL indicates to "dt_score" that sub- 
files are involved. This mainline works with the other components we have 
created to actually perform the specified file maintenance. 


ote: d-tree is first and foremost a powerful toolbox of functions. The "run" , 
‘catalog", and programs created by the "catalog" are good examples of 
programs that can be written with the tools. The user who understands each 
ool and how they work together will get the most out of d-tree. As you will see 
n later sections of the manual, we strongly encourage looking at the 
‘dt_score.c" mainline. It, again , is a good example of how to apply the tools in 
dynamic manner. 


"posting.h" - Next, look at the header file "posting.h". First, it contains the "C" 
structures for the six files. Next, is the DODA followed by the incremental struc- 
tures (if selected) . Other entries which will be new to you are shown below. 
These entries are explained in detail in later sections. Simply note them for now. 
No changes are necessary at this time to these entries. 


posting.h 


DTTFUNCT DTSFUNCTCE] = € ae 

; Sia DT_NULFP } 

3; 

ip fenie oF nara codes aoara] 
DTTHRDCD DTSHRDG1ICI] = { 


“7™ base pointer ». ref num hou many entries in definition table */ 
{ (TEXT ™) DTSDDODA ,DTKDDODA , sizeof(DTSDDODA) 7 sizeof DATOBJ) } 
€ (TEXT ™) DTSISEGS ,DTKISEGS , sizeof(DTSISEGS) 7 sizeof( ISEG) ‘2 
(TEXT *) DTSIIDXS ,DTKIIDXS , sizeof(DTSIIDXS) 7 sizeof( IIDX) a 
/ a 
4 + 


¢ 

{ (TEXT *) DTSIFILS ,DTKIFILS , sizeof(DTSIFILS) sizeofC IFIL) 
€ (TEXT ™) DTSFUNCT ,DTKFUNCT , sizeof( DTSFUNCT) 
{ 
+ 


sizeof( DTTFUNCT) 
(TEXT *) @ ~~ ».» @+ Z** terminaton Indicator */ 
wifndef COMPILE 
DTTHRDCD *DTSHRDCDUDTHRDCD] = { 
DTSHRD@1, 
+; 
tendif 
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“posting.dts" - the d-tree script. We must modify the d-tree script to specify ex- 
actly how we want the file interaction to occur. Let’s look at it next. The first sec- 
tion looks very similar to the scripts we have reviewed before for the single-file 
maintenance programs. It pertains to the file which we designated as "MASTER", 
in our case the "trans" file. Look through this section. It terminates with the com- 
ment: 


/*** SUBFILE INFORMATION ***/ 


Before we continue let’s take a look at what our objective is for this program. 
We want a "trans" posting program, where we can break each transaction entry 
down by both the account number as well as the project. Each transaction can 
apply to more than one project, as well as more than one account. This break- 
down is provided by entries in the "dist" file. The maintenance of this can be ac- 
complished by providing a posting screen for the "trans" information, along with 
a scrollable portion of an entry screen which allows multiple ("dist") entries per 
transaction. In turn, we are about to modify the d-tree script so that our entry 
screen will look something like this when the program is executed: 


Apr 26 ; ec - oystem 
Transaction Master File 


Trans Reference Number: ] 
Transaction Type: 

Transaction Date: 

Transaction Amount: 

Trans Customer/Vendor No.: 

Transaction Description: 


One to 
Many 


Breakdown Amount 


D> 
‘f) 
0 
o 
= 
3 
ce 
~U 
se | 
° 
C. 
@ 
i?) 
ce 


— 


L_ 


Back to the script following the line: 
/*** SUBFILE INFORMATION ***/ 


This second section describes the second file selected which was the "dist" File. 
As you recall, we specified this as a subfile of the "trans" File. You will notice 
that the first specification for this file looks like this: 


Silica iso ieee eee oases nase deacon iin to ag 
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posting.dts 
7x SUBFILE INFORMATION »>/ 


IMAGE( trans) {NO_CLS} {LSTFLD_ADVANCE} {FRSFLD_BACKUP} {(BASE_ROU=77) 


FIELD(C trans) 

7% Symbol Nare Input Attribute Output Attribute Input Order I/0 Special * 
dis ref NONE NONE Z2 “* Transaction Refern 
dis_amt NONE NONE 3 “7* Transaction Amount 
dis_acct NONE NONE 4 7* Account Number */ 
dis_proj NONE NONE 5S /“* Project Number */ 

7 AHS 


This image (identified with the reference name "trans" - not related to our "trans" 
file name) represents the display format for the subfile records. Notice the ques- 
tion marks following the BASE ROW parameter (base row is the first row on the 
screen that this image should start). Throughout the script file, d-tree left ques- 
tion marks to indicate values which we must supply before the script is useable. 
In this case, we must specify the row within the "master" image where the sub- 
file display area (scrollable region) is to begin. First, let’s go back and adjust our 
"master' image to that we can display this scrollable region in a sensible place. 
Modify the image for "master’ to look like this: 


posting.dts 
IMAGE( master) {LSTFLD_ADVANCE} 
@DATE Small Project Acct. System @TINE 
Transaction Master File 


Trans Reference Number: 
Transaction Type: 
Transaction Date: 
Transaction Amount: 

Trans Customer/’Vendor No.: 
Transaction Description: 


Breakdown Amount Account Pro ject 


Clean up the ‘master’ IMAGE by moving the fields 
up and straightening the input lines. Add “dist” 


colurm headings on line 11, leaving line 12 and 
below blank. (Note: @DATE is considered to be on 
line 1.) 
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We can then go back down to the IMAGE(trans) definition and specify a base 
row of 12 for the subfile display area. Note that on an IMAGE definition, line 1 is 
considered to be the first line below the IMAGE keyword. When a BASE_ROW is 
defined, it is simply an offset that is added to the lines as they are defined in the 
IMAGE section. You will want to delete the three blank lines which follow the 
IMAGE(trans) line, otherwise your scrollable region will start on line 15. 
(BASE_ROW of 12. This image starts with three blank lines 12, 13, and 14, with 
fields starting on line 15.) 


As you will see below in the SFL_MAP section , when subfile records are written 
to disk, you have the option to MAP (copy data from) fields from the primary 
(parent) file (‘trans") to the subordinate (child) file ("dist"). In our file definitions 
we have provided a means to relate these files by defining a transaction 
reference field in both files. As you will se below, when we write each "dist" 
record to disk, we will MAP the transaction reference number from the "trans" 
file to the "dist" file. In turn, we do not have to display (or maintain) the transac- 
tion reference number for the "dist" file on the screen. Modify the IMAGE (trans) 
and FIELDS (trans) sections as follows: 


1) removing the two blank lines described above. 

2) removing the transaction number. 

3) adjusting the spacing so that the fields we are displaying will line up under 
the column headings defined on IMAGE(master). The result of these changes 
should look as follows: 


posting.dts 
7uue SUBFILE INFORMATION »7 


IMAGEC trans) {NO_CLS} {LSTFLD_ADUANCE} {FRSFLD_BACKUP} {BASE_ROU=12} 


FIELD( trans) 
7* Symbol Name Input Attribute Output Attribute Input Order 1/0 Special ™ 


dis_ amt NONE NONE 1 “* Transaction Amount 7 
dis acct NONE NONE Z “* Account Number */ 
dis_proj NONE NONE 3 7* Project Number */ 


7 y00de re / 


The next section of the script defines the Subfile Specifications. This is what 
links the subfile (Distribution File) to the master file (T ransactions), along with 
other requirements to process the subfile. 


> 7 EEE tree 
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Again, notice that d-tree placed question marks where we need to provide 


values: 


posting.dts 
SUBFILE( trans) 
SFL_IMAGE( trans) 7” image to sfl record display(image that rolls)*/ 
SFL_RECORDS( 77) /* total number of records in subfile */ 
SFL_LINES( 77) 7* total number of lines sfl takes up on screen */7 
SFL_TITLEC 77777) 7 optional...image to be displayed as the title 


SFL_TARGET 

“7* key symbol name fields for target prefix 
TTTTTTT ‘ee egw: 

SFL_MAP 

7/* parent field child field length */ 
TTTTT T7777 
SFL_SEQ TTTTT 


SFL_MUSTHAVE 
T7777 7 fields that must exist to make a valid sfl red */ 
7 OOO 


SUBFILE(trans) - First we give this subfile definition the reference name " trans" 
which our programs can use to refer to this subfile. Note that the word "trans" 
here has nothing to do with our file "trans". It is simply the reference name for 
this subfile. 


SFL_IMAGE(trans) - Next we define the IMAGE that is going to be used as the 
scrollable region for this subfile. We have just completed our work on the "trans" 
image. This is the image we define to be used by the subfile. 


SFL_RECORDS(??) - d-tree manages subfiles by two different methods. 


e 1) MEMORY SUBFILES - When the SFL_ RECORDS keyword is given 
a value other than one (1), we are defining this subfile as a memory — 
subfile. A memory subfile assumes that all information (records from 
the detail file) can be loaded into memory at one time. The size (or 
number of detail records allowed) of the subfile is restricted by the 
amount of memory available. Although this method does have this 
restriction, it does have advantages. d-tree can process a memory 
subfile much faster because all records are in memory. This method is 
best used when our application can define a limited number of detail 
records. In our case, we are breaking transactions down by "account" 
and "project". It is valid for us to assume that the user of this "posting" 
program will not need to "distribute" a single transaction between more 
that 50 "accounts" and "projects" (in reality they will need only 5 to 10). 
In order to give them plenty of leeway, set the number of subfile 
records to 50 as follows: 


SFL_RECORDS(50) 
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e 2) UNLIMITED SUBFILES - d-tree will manage paging subfile records 
on and off of disk, providing the capability to have an unlimited number 
of records in the subfile. (NOTE: Limited only by physical disk space). 
This is done by simply defining the number of subfile records to be 
one (1) as follows: 


SFL_RECORDS(1) 


(NOTE: Keep this in mind later when you work with the "catalog" 
program. We use a subfile in that program to maintain the fields in a 
file. We ship this subfile as a fixed number, allowing 48 fields per file. 
You can increase this number if memory is available (UNIX/XENIX 
Ok....DOS is tight) or change this to allow an unlimited number of fields 
per file by modifying the catalog script (dtcatlog.dts"). The modification 
involves changing SFL_RECORDS(48) to SFL_RECORDS(1) in the 
SUBFILE(master) definition.) 


SFL_LINES(??) - Next we must specify the total number of lines the scrollable 
region is to occupy on the screen. This number should be evenly divisible by 
the number of lines used in the subfile image (in our case 1 line). This will con- 
trol how many records will be displayed in the scrollable region at one time. 


Example: If our subfile image takes up three lines and we define the total num- 
ber of lines to be nine, we will see three records on the screen at a time. We 
must also consider the number of subfile records we defined previously (unless 
it is unlimited). \f we define nine lines for the scrollable region, and each record 
takes up three lines, we need make the number of subfile record divisible by 
three , fe: 21. 


Here are the rules: 


e 1) The number of records in the subfile has to be divisible by the 
number of records per screen. 


@ 2) The number of records per screen is determined by the number of 
lines the subfile occupies on the screen (SFL_LINES) divided by the 
number of lines required by each subfile record. (number of lines in the 
subfile image-SFL_IMAGE). 

@ 3) The number of lines on the screen (SFL_LINES) must be divisible by 
the number of lines defined in the subfile image-(SFL_IMAGE). 


In our case, our image ("trans") only takes up one line. Let's define SFL_LINES 
to be 10 as folows: 
SFL_LINES(10) 


We have already set SFL_RECORDS to 50, thus we will have ten (10) records 
per page in the subfile, and are able to roll (page up/page down) though five (5) 
pages of subfile records. 
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SFL_TITLE(????) - Subfile title (optional). This keyword provided a means to 
define a separate image which will automatically be displayed the first time the 
subfile is displayed on the screen. It is useful for subfile column headings when 
it is not appropriate to place these headings on the primary image. Because we 
have placed our headings on our primary image we have no use for this feature 
in this specific application. Delete or comment out this line from the script. 


SFL_TARGET - Subfile Target. This keyword is used to define the connection 
between a subfile and a data base (c-tree) file. The SFL_TARGET definiton is 
made up of three parts: 


e Key Symbol Name - Enter the symbolic name of the index which will 
be used to load this subfile. This will be the name of an index defined 
for the file from which we want to access records. In our case , we 
want to access records from the "dist" file. We have defined a key field 
(transaction reference number) in the "dist" file, as well as an index 
over this field. You provided a key symbol name when you defined this 
key in the catalog. If you do not remember this key name, either go 
back into the catalog and look it up, or even easier, this symbolic 
name is defined in the source specs which were created for this 
program. Look at the incremental file definitions in "posting.h" (or if a 
parameter file was created, look at "posting.p"). We willl assume the 
key was named "dist_ref_idx" for illustration purposes. 


e Fields for Target - Enter the fields to be used to make up a "target" 
field that will be used in accessing the provided index when loading the 
subfile. d-tree automatically combines all fields and performs proper 
transformation on the fields in order to make up the “target”. In our 
case, we will use the "transaction reference number’ from the "trans" 
file. We want to load all records from the "dist" file that relate to a 
single entry in the "trans" file. The relation is done with the "transaction 
reference number". Enter the field names you used when you defined 
the “trans” file for the "transaction reference number’. We will assume 
“trn_ref" for our illustrations. 


e Prefix - The prefix is an optional entry. If entered it will be the first 
segment used when the "target" is formed. We will not use this feature 
in this application. 
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SFL_MAP - subfile map. The subfile map provides the capability to MAP (copy) 
data into subfile records as they are written to disk. Its most common use is to 
coordinate changes in the master file with related records in a subordinate file. 
For instance, if the user changes the "transaction reference number’ in a record 
from the "trans" file , we would want the "transaction reference number’ in each 
corresponding subfile record, to automatically be changed as well. We would 
therefore define that we want the "transaction reference number' from "trans" file 
to be mapped into the "transaction reference number’ in the "dist" file. The 
"trans" file is considered the parent, and the "dist" file is the child. Enter the 
proper fields in your script. (See the illustration on next page.) We have as- 
sumed the following field names: 'trn_ref' for "trans" file and "dis_ref" for "dist" 
file. 


Some of you may have noticed a possible oversight in our design of the "dist" 
file. Because we are loading the subfile using a key that is solely defined for the 
"transaction reference number’ (one key segment) , we have no guarantee that 
the subfile records will be consistently loaded in the same order each time. In 
otherwords, if we key in three subfile ("dist") records in a certain order for a 
specific "trans" record, and then load the subfile again, we will get the proper 
three records from the "dist file" , but they may not be in the same order that 
we keyed them. The solution to this is as follows: If we had defined a "sequence 
number" field in our "dist" file, we could then define the key used to load the sub- 
file to be made up of two key segments (two fields). The first is the same as 
before, the "transaction reference number’. The second segment (field) would 
be the "sequence number". If, as each subfile record was written to disk , a se- 
quence number was mapped into this field, subsequential access to this file, 
using this index, would insure that the records were loaded in a consistent man- 
ner. The mapping of this sequence number into each record is obtained by 
using the special keyword "SFL_SEQ " as the parent field in the SFL_MAP sec- 
tion. The "sequence number' field is the child. We did not place a "sequence 
number" field into our "dist" file, so we will not use this feature now. Delete (or 
comment out) the line in the script where the SFL_SEQ has been defined. 
Remember this observation when you run the "posting" program. 


SFL_MUSTHAVE - Subfile must have. The "SFL_MUSTHAVE" specification is 
used to identify any field or fields in the subfile record which must contain data 
before the record is considered to be a valid record. Simply list the field(s) that 
must contain data before this record is considered valid. In our case, we will not 
consider an entry unless there is an amount entered in the record. Thus, enter 
the field that you defined as the amount field in the "dist" file in this section. We 
will use "dis_amt" for our illustration. 
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The following illustrates the completed subfile section: 


posting.dts 
SUBFILE(C trans) 
SFL_IMAGE( trans) ”* image to sfl record display(image that rolls)/ 
SFL_RECORDS(S@) /* total number of records in subfile */ 
SFL_LINES( 18) 7* total number of lines sfl takes up on screen »*/ 
/* SFL_TITLEC 77777) optional...image to be displayed as the title */ 


SFL_TARGET 

7% key symbol name fields for target prefix / 
dis_ref_idx trn_ref 

SFL_MAP 

/* parent field child field length */ 
trn_ref dis_ref 

7% SFL_SEQ TT7T7TT “/ 


SFL_MUSTHAVE 
dis_amt /™* fields that must exist to make a valid sfl red */ 


7 YAS 


The next and subsequent sections are identified with the comment: 
/*** VALIDATION FILE ***/ 


When a file is selected as a "VAL" (validation) type, specifications are witten for 
the following d-tree keywords: EDITS, IMAGE, FIELD, SCAN, MAP. For every 
"VAL" file selected these specifications are repeated with the proper data for the 
file selected, but using the same keyword reference name. It is your respon- 
sibility to provide unique names for these keywords as shown below. For our 
discussion we will use the Account Code file. After completing the following 
steps to provide the "account" validation, repeat these steps for the other three 
files. 


Step 1 - EDITS keyword. The ability to validate a field as a proper entry in 
another file is provided by the edit type "VALIDATE". Therefore we have created 
a default edit entry. You must complete this edit definition: 


EDITS(validate) /* Place this edit where applicable */ 
Invalid ??? Error Text ???_fieldname VALIDATE ???_index valmap valscan 


First, we need to ensure that the edit is defined in the proper EDITS section. The 
account number we are validating is located within IMAGE(trans). We do not 
have an EDITS(trans) section defined yet, so we must make one. Change the 
name from EDITS (validate) to EDITS(trans). If there already was an EDITS sec- 
tion associated to the applicable image, we would delete the EDITS (validate) 
keyword and move the default edit specs to the proper EDITS section. 
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The edit default specifications require the following information to be provided 
where d-tree placed question marks: 

@ specify an appropriate error message you wish to display if the edit 
fails. 

e enter the symbolic name of the field to be edited. For our illustration 
we will use "dis acct". 

e enter the symbolic index name to be used for the validate. In this case 
it will be the key over the account file by account number. For our 
illustration we will use act_code_ idx. 

e change the associated map name (valmap) to a unique name. We will 
use "actmap". 

e change the associated scan name (valscan) to a unique name. We will 
use "actscan". 

The result of these changes should look as follows: 


posting.dts 
EDITS( trans) “7 Place this edit where applicable */ 


Invalid Account Number dis acct VALIDATE act_code_idx actmap actscan 


You may prefer to move the EDITS(trans) section to be under the IMAGE (trans) 
and FIELD(trans) keywords so they they reside together in the script. 


STEP 2 - MAP keyword. First change the reference name given to the MAP to 
the same name defined in the EDITS section. ( ie: MAP(actmap) ) Besides simp- 
ly validating a field as a valid entry in another file, the "VALIDATE" edit type 
provides for two more features. 


@ 1) Allows the definition of a scan, by which the user can scroll through 
the valid entries in the associated file, and select (or optionally add) a 
valid entry. The scan is defined in step 3. 


@ 2) Once a valid entry is selected, the associated MAP is executed 
(actmap). This associated map typically defines data to be mapped 
(copied) from the selected record to any defined field(s). The one field 
we will want to specifically map is the field that we are validating. In our 
case, if an account record is selected, we will want the account 
number field from the “acct" file to be mapped into the account field in 
the "dist" file. This is achieved via the following map definition: 


posting.dts 
MAPC actmap) 


7% source field desination field Map Type length »/ 
act_code dis_acct REPLACE 
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STEP 3 - SCAN , IMAGE, FIELDS keywords for validate. The last section for 
each validation file is the scan specifications as described earlier. The combina- 
tion of the IMAGE, FIELD, and SCAN keywords should be familiar. Apply ap- 
propriate changes, specifically providing the unique reference name as defined 
in the edits. (actscan). Your changes should look similar to this: 


posting.dts 

IMAGECactscan) {LSTFLD_ADVANCE} {FRSFLD_BACKUP} 

@DATE Small Project Acct. Systen @TINE 
Transaction Master File 


Select 
Enter Desired Option: __ 
Press ESC ESC to EXIT 
FairCom (c) 1988 
FIELD(C actscan) 
7* Symbol Name Input Atribute Output Attribute Input Order Special 
option NONE NONE 1 


IMAGECactscanroll) {NO_CLS} {LSTFLD_ADVANCE} {FRSFLD_BACKUP} 


FIELDCactscanroll) 

7* Symbol Name Input Attribute Output Attribute Input Order I1/0 Special »* 
counter NONE NONE 1 
act_code NONE NONE Z 7™ Account Code */ 
act_desc NONE NONE 3 “™ Account Descriptio 
act_cat NONE NONE 4 /7* Account Catagory * 
act_bal NONE NONE S “™ Account Balance */ 


SCANCactscan) CIMAGE_OUT=actscan} CIMAGE_ROL=actscanroll} {IMAGE_INP=actscan} 


BE SURE TO CHANGE ALL OCCURENCES OF THE NON-UNIQUE 
REFERENCE NAMES TO UNIQUE NAMES WITHIN EACH VALIDATION FILE 
SPECIFICATION! 


Repeat these steps for the other validation file specifications. 


lf the changes are complete, you can compile the program "posting.c" (or if you 
submitted it to the compiler queue, simply select “Execute Compiler Q" from the 
catalog main menu.) 


The program is now ready to run. Imagine how much work this process would 
have involved before d-tree! 
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posting.rts - If you select the r-tree option when you created source specs from 
the catalog, review the "posting.rts" file. What the "catalog" program did, is to 
simply dump the selected files one after the other into a default r-tree script. 
This script is not ready to run if more than one file was selected. What the 
"catalog" did do is save you alot of grunt work. The majority of the reports re- 
quirements are in the script. It’s up to you to move things around to create your 
specific report. The following is a sample of what is dumped to the r-tree script: 


posting.rts 
START 
7% UIRTUAL */ 
SEARCH 
FILE “trans.dat™ ALL 
SELECT 
ALL 


7* CONTROL */ 
“* SORT */ 
7* ACCUMULATOR */ 


DISPLAY 
DEVICE 3 
PAGE_LENGTH 66 
SCREEN_LINES 24 


IMAGE 

PAGE_HDR 

+ 

+ Date: Oxxxxxxxx Page: @xxx 
SYS_DATE PAGE_NO 

+ 

BODY 


ee aegis i era on i ne eee acta ag ge EL ee 


+ 


+ @OXXXXXXXXXXX 
trn_ref 

+ @XX 
trn_typ 

+ @XXXXXxXX 
trn_date 

+ _99gs9s3585 
trn_amt 

+ @XXXXXXXXXXxXxX 
trn_vncust 

+ = ORXXXXXAKXAXXXXXXAXXXXXXXXXXXXXXXXXXXXXXXXX 
trn_desc 

PAUSE 


EXERCISE: 


Fine tune the single-file and multi-file maintenance scripts to make the Small 
Project Accounting Package more to your own liking. 
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2.5 The r-tree Interface - Tutorial 


To this point we have focussed on constructing maintenance programs. This 
session will deal with another necessity in developing a complete system - 
Reporting. In this session we will illustrate d-tree’s ability to provide a “front end" 
interface into the report generation capabilities of r-tree. r-tree is FairCom’s 
powerful report generator, providing search, select, sort, of data base informa- 
tion as well as a "report-painting" interface. 


There is always more than one way to approach a problem. This tutorial il- 
lustrates but one technique. Let’s start by explaining the general flow of this ap- 
proach. 


When a report is desired by the user, a "report prompt screen", presenting the 
fact that the specific report was selected, is displayed. Optionally the user is al- 
lowed to provide input which will have some control as to the output of the 
report. A "base r-tree report script" must exist providing the report definition. 
This should be a complete script which can be passed to r-tree’s "report" 
function for execution with the following exception. Any definition lines in the 
VIRTUAL, SEARCH, SELECT, or SORT sections of the r-tree script that will 
change as a result of user input, should be “left out" of the script. The different 
variations of the "left out" definition lines are defined in a d-tree script with the 
RTREE ability. When the report is executed, the proper variations are 

‘inserted" into the r-tree script. If input from the user will do nothing to change 
the report (no input fields defined on prompt) then the base r-tree script is a 
complete script. 


The "report prompt screen" and the "inserted" lines are defined in a d-tree script 
with the IMAGE and RTREE abilities. 


Once the user completes the "report prompt screen entry process, the 

“base r-tree report script" is read one line at a time, writing each line to the 
"report work file". Before each line is actually written it is checked to see if is con- 
tains a r-tree keyword. If so, and this keyword is also defined in the d-tree script, 
the user’s input is scrutinized to determine the proper definition variation line to 
be "inserted". This definition is then written to the "report work file". This work 

file is then used by the r-tree "report" function to execute the report. 


In this approach we have split the logic up into two seperate programs: The first 
program will be refered to as the "prompt program". The second program will 
be refered to as the "report program". 
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e Prompt Program: The prompt program makes the call to d-tree’s 
r-tree interface function DT_RTREE. This function will display the 
“prompt screen", check the input, and build the "report work file" 
(DTRTS.BAK). It then will call (turn control over to) the 
“report program". 

e Report program: simply contains the call to r-tree’s "report" function. 
The script to execute is the parameter passed to it by the 
“prompt program". The "report work file" name is this parameter. 


To illustrate this technique let’s first create a simple Customer Master Listing. 
Once we have it running we will add customer range ,select and sorting options. 
The nice part about d-tree is that the catalog program does the majority of the 
work. 


Begin by running the catalog and clear the compile que. Now enter the Data 
Dictionary. The first things we must do is select.the files we will be using to 
produce this report. Take the "Select File" option. Select the following items for 
d-tree to generate: 


e DODA specs: Will create the doda needed by r-tree. 


e Incremental Structures or 
Parameter Files: Used to open the files. 


e d-tree Script: Create a default "prompt screen". 
e r-tree Script: Create a default "r-tree report script". 


Enter the name "custlist" to be used for the source, scripts, and executable | 
files. Say (Y)es to the program dictionary option ,then enter a ’R’ fora "report 
type" program. The data dictionary data file prompt screen will then be dis- 
played. Enter a '0’ in the first field to present a file selection screen containing a 
list of all the available files in the data dictionary. Place a ‘1’ in front of the Cus- 
tomer file then press the POST key. d-tree will then create the following files: 


e custlist.p- | Only if Parameter file is selected. 

e custlist.h- = containing the DODA and incremental 
structures (if selected). 

e custlist.c - mainline for prompt and report programs. 


e custlist.dts - default d-tree script for prompt screen. 
e custlist.rts - default r-tree report script. 
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The program dictionary entry screen will then appear. An entry here will provide 
a program to. data file cross-reference when running catalog reports. Enter som- 
thing like the following: 


Program Dictionary 


Add or Update Program to Code Dictionary 


program name: custlist 


program version: ft ek: SR 

program system name: Small Project Accounting _ 
program description: Customer Master Listing 
program type: REPORT 


Escape back to the main menu of the Catalog and execute the compile queue 
to compile our "prompt program". Once the compile is complete exit out of the 
catalog program, back to your operating system. 


Let’s take a look at the d-tree script that was created. Using your text editor, 
bring up the file "custlist.dts". A default prompt IMAGE has been created. 
Change this IMAGE to apear as follows: 


IMAGEC report) {LSTFLD_ADUVANCE?} 
@DATE Enter Your Report Prompt Title 


«xxx ENTER YOUR REPORT PROMPT SCREEN HERE >> 


FIELD( report) 
7* Symbol Name Input Atribute Output Attribute Input Order Special */ 
option NONE NONE 1 


Change This To This— 


| IMAGEC report) {LSTFLD_ADUANCE} 
| @DATE Customer Master Listing @TINE 


You are about to run a Customer Master Listing 


Note: we took 
out the FIELD 


Ability for we 
Press ESC ESC to Cancel the Report have no input 
+— [fields. 


d-tree Reference Guide 2-55 


2.5 The r-tree Interface - Tutorial 


Next a report message IMAGE has been created. Change this screen to look 
like this: 


IMAGE( message) 


“MxM ENTER YOUR REPORT MESSAGE SCREEN HERE «0 
®DATE This Message Will Display When Report Starts Running @TIME 


Change This—! To aol 


IMAGE(C message) 
@DATE Small Project Accounting System 
Custorer Master Listing 


Report Now Running.... One Moment Please 


This first report will be a simple listing, without any “run-criteria" entered by the 
user. Because we desire no criteria the "insert" definition lines that have been 
placed in the script are not necessary. Delete these lines as shown: 


custlist.dts 
RTREEC report) 


USES_IMAGE( report) = 

USES_SCRIPT( custlist. rts) 
REPORT_PROGRAM custlist. exe) 

RUN_IMAGE( message) | 

CALL_TYPE¢C EXECL) 


7 r—-tree criteria Substitute / 
“7™ keyuord fields String “/ 


Delete from this line 
Thru and including 
THI FAAG. ok hae eee 


SEARCH NONE FILE “?77.dat" ALL 
777 FILE “?77.dat" USING _KEY 777_KEY C “{7773" 
777 ~=FILE “?77.dat" USING KEY 777_KEY  “{7773" 
777 
777 ~=FILE “777. dat" USING _KEY 777_KEY C “777 "€7773" J 


SELECT NONE ALL 
UIRTUAL NONE LEAVE_OUT 
SORT NONE LEAVE_OUT 


>=. 
2-56 d-tree Reference Guide 


2.5 The r-tree Interface - Tutorial 


Our d-tree script is now ready. We have already compiled the "prompt 
program", which uses this script, from the compile que in the catalog. The 
catalog has also created a default r-tree script. This script is ready to run so for 
this example we will not modify it. You may want to view this r-tree script to see 
the work the catalog saved you. See the file "custlist.rts". We have one last 
necessity before we are ready to run the report. The "report program" must be 
compiled. Remember, the "report program" contains the r-tree "report" function 
and is called by the "prompt program". It just so happens that when we created 
the source for the "prompt program" from the catalog, we also created the 
source for the "report program". Both mainlines are defined in one ".c" file, 
which is controlled with #define. The catalog creates this ".c" with the "prompt 
program" definition set (#define RPT PRMPT). In order to create the "report 
program" we must simply take out the #define RPT PRMPT (comment it out in 
the code) as show below: 


custlist.c 


7” udefine RPT_PRMPT */ an |e 
#ifdef RPT_PRMPT Comment out this #define 


7% r—-tree report prompt program */ for “report program”. 
tinclude “dt_defin.h” 

tdefine DT_DTS “custlist.dts” 

tinclude “dt_dtrts.c” 


telse 


“7% r-tree report execution program */ 
tinclude “dt_defin.h” 

tinclude “dt _globl.h” 

tinclude “dt_ddoda.h” 

tinclude “custlist.h" 

7* wdefine DTRETPGM define return program */ 
tinclude “dt_dtrpt.c” 


This "report program" has got to be compiled. In the d-tree script, were we 
painted the "prompt screen", there is a keyword in the RTREE section which 
defines the name of the "report program". This is the name of the program 
called by the “prompt program" (i.e.: REPORT _PROGRAM(custlist.exe). This 
name has been defaulted to the same name as the "prompt program". One or 
the other has to be changed. Do one of the following (but not both): 


1) Rename the "prompt program" executable created by the compile que, and 
compile this ".c" file. You would then call the report using this “new name" 
which will prompt the user and then call the "report program" (which has the 
Original name) to run the report. Remember this original “report program name" 
was defaulted in the d-tree script by REPORT PROGRAM(custlist.exe) 


2) When compiling the ".c" file, give the executable a different name. If this is 
done you must also go back into the d-tree script (custlist.dts) and change the 
report program definition. Change REPORT _PROGRAM(custilist.exe) to reflect 
your new name. 
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After they have completed compiling, test the report by executing the "prompt 
program". (Note: You may first wish to verify that you have data in your cus- 
tomer file to use in your test.) With minimai coding, we used d-tree to generate 
an r-tree report. d-tree takes a lot of the "grunt" work out of creating reports by 
placing the fields and formats in the r-tree script. The user is then expected to 
modify these scripts finalize the report. See your r-tree documentation. 


Now lets add the ability for the user to add some "run-time" report criteria. 
Change the d-tree script "custlist.dts" to look as follows: 


custlist.dts 
IMAGE(C report) {LSTFLD_ADUVANCE} 
@DATE Small Project Accounting System @TIME 
Customer Master Listing 


From Customer Number? 
To Customer Number: 


Select only the following State: __ 


Sort Report in Zip Code Order: __ 
Center a °Y’ or leave blank) 


Send Output to Device: _— (default: 1, Printer #1) 
(1 = Printer #1; 2 = Printer #2: 3 = Screen: 4 = Disk File) 
FIELD( report) 
7* Symbol Name Input Atribute Output Atribute Input Order Special */ 
opti NONE NONE 1 
optZ NONE NONE 2 
opt3 NONE NONE a 
opt4 NONE NONE 4 
optS NONE NONE S 


Leave the message screen the same. Add "user criteria" with the d-tree RTREE 
ability as follows: 


custlist.dts 
RTREEC report) 


USES_IMAGE( report) 1Remember: “Report Program” name} | 
USES_SCRIPT( custlist. rts) | 


REPORT_PROGRAM custlist. exe) 
RUN_IMAGE( message) This is assumed to be the 
CALL_TYPEC EXECL) index name over the customer 
7% r—tree criteria Substitute file by customer number. 

7* keyword fields String “/ 


SEARCH NONE FILE “customer. dat’ ALL 
opti FILE “customer. dat’ USING_KEY customeridx {€ ‘{opti}” 
optZ FILE “customer.dat” USING_KEY customeridx “{opt2}" ] 
opti 
optZ FILE “customer.dat’” USING_KEY customeridx { “{opti}" “{C{optZ}” J 


SELECT NONE ALL | 

opt3 cust_state={opt3} Customer state field name} 
VIRTUAL NONE dev INTZ 2 1 . 

optS dev INTZ Z {optS} 


SORT NONE LEAVE_OUT : & Customer Zip code field nare 
opt4 NO_MOD cust_zip 


32n000-—-—-—— 
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Change the r-tree script “custlist.rts" to look as follows. Note: we have com- 
mented out the lines where the instructions say “remove': 


custlist.rts 


START 
VIRTUAL | 1. Un-Corme)ent the VIRTUAL Keyword. 


SEARCH 
7/* FILE “customer.dat’’ ALL */“” +—j] 2. Remove this search line. It will 
be inserted at runtime from your 
definition in the d-tree script, 
Leave SEARCH keyuvord alone. It 
must remain in the r-tree script. 


Sie F 
7% ALL a Remove this select line. It also 
will be inserted at runtime. Do 
7% CONTROL */7 not remove the SELECT keyword. 
soRT <———— | 4, Un—Corment the SORT Kequord. 
7% ACCUMULATOR */ - Change the DEVICE definition. 
Was DEVICE 3 ... Now DEVICE dev 
| DISPLAY The d-tree script’s VIRTUAL will 
DEVICE dev control the output device. 
PAGE_LENGTH 66 
os . Change the rest of the script as 
desired. 


Run the report, and supply various search, select, and sont, criteria. Also note 
the use of the VIRTUAL keyword to control where the output is to be directed. 


SUMMARY: The technique of splitting the reporting process into two different 
programs has the following benifits: 
e 1) r-tree alone takes up a significant amount of code space. This allows 
a program to call a report, without the additional r-tree code residing in 
the program. 
@ 2) Because the "report program" processes the script that is passed as 
a parameter, we are able to create ONE "report program" which can 
handle an unlimited amount of reports, by simply changing the script 
that is passed to it (no need to compile over and over). 
@ 3) Ina muti-tasking environment, the "report program" can be 
submitted to backgroud for processing, freeing up the user. 


Refer to the RTREE ability in Section 7 for a further information. 
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2.6 Menus - Tutorial 


From Session 1 of this tutorial through Session 5 we have learned how to use 
the d-tree toolbox to develop the many pieces of a Small Project Accounting 
System. We must now tie all these pieces together to enable the users to ac- 
cess each program easily. Traditionally this equates to using menus. Fortunate- 
ly, the catalog provides a quick way to create menus. Follow these steps: 


e 1) Enter the catalog and clear the compile que. 


e 2) From the Data Dictionary Menu, select the "SELECT FILES" option. 
Although we need no files for menus, we will take advantage of this 
option’s ability to create d-tree scripts and mainlines. 

@ 3) To Create a menu program called "menu" make entries on the select 
screen as follows: 


System Catalog 
Select of Group of Files 


Select the Desired Source Specs to Create 


Create a Parameter File 

Create C Source Structures 

Create a Data Object Def Array (DODA) 
Create Incremental Structures 

Create a d-tree Script 

Create a r-tree Script 


Enter Source File Name: menu 


Do you want to make an entry into the Program Dictionary: Y_ 
Type of Mainline to Create 
(Maint Pgm ; (R)-tree Report Pgm ; MentU) Pgm 
Enter (M,R.or UD): CU J 


e 4) Once the d-tree script has been created, the catalog prompts for an 
entry into the program dictionary. Place an entry something like the 
following so this menu program will appear in the cross reference 
reports produced by the catalog. 


Program Dictionary 


Add or Update Program to Code Dictionary 


program name: menu 


program version: Pe : 

program system name: Small Project Accounting _ 
program description: System Master Menu 

program type: MENU 
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@ 5) Now return to the catalog main menu and execute the compile 
queue. This will compile your menu. 


@ 6) We must now "paint" our menu to fit our needs. Edit the file 
“menu.dts". As you can see, the catalog has created a default d-tree 
script which looks like this: 


menu.dts 
IMAGEC menu) C{LSTFLD_ADUVANCE} 
@DATE Enter Your Menu Title @TINE 


mMMoM ENTER YOUR MENU SCREEN HERE >< 


FIELD( menu) 
7* Symbol Name Input Atribute Output Atribute Input Order Special */ 
option NONE NONE 1 
MENUC menu) 
USES_IMAGEC menu) 
7M Call Criteria Type of Call Call Value ™/ 
option=1 CURSOR=name EXECL my program 
option=1 CURSOR=nare SYSTEM my_program 
option=1 CURSOR=nane CALL my_function 
option=1 CURSOR=nare RETURN 1 


@ 7) We will start by creating a simple menu. Change the script to look 
like this: 


menu.dts 


IMAGEC menu) {LSTFLD_ADVANCE} 
@®DATE Small Project Accounting System @TINE 
System Master Menu 


1. Customer Master Maintenance 4. Valid Account Codes Maintenance 
Z. Project Master Maintenance 5S. Post Transactions 
3. Vendor Master Maintenance 6. Report Menu 


Select Desired Option: 


Press ESC ESC to EXIT 


FIELD( menu) 
7% Symbol Name Input Atribute Output Atribute Input Order Special */ 
menul NUMERIC NONE 1 
MENUC menu) 
USES_IMAGE( menu) 

7M Call Criteria Type of Call Call Value */ 
menui=1 EXECL customex.exe —Emenu 
menul=Z EXECL project —-Emenu 
menuil=3 EXECL vendor —Emenu 
menul=4 EXECL account —-Emenu —-E pgm return 
menui=S EXECL posting —Emenu option. 
menul=6 MENUCALL menu 


iat lamented aaa daledatscetamsstaa donde eee ts dana anemia ce a 
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e Notice the attention to the -Emenu in the illustration above. One of the 
mainlines supplied with d-tree is "dt_score.c". This is the mainline used 
by most programs produced from the catalog. It is also the mainline 
for the "run" program. A parameter passed to this mainline logic with a 
-E (execute upon exit flag) is considered to be an executable file name 
that is to be called upon exit. This provides a means for the "called" 
programs to return the the "caller'. Here we use it to return to the 
menu. 


e 8) Save the d-tree script, and run the "menu" program. 


We created a simple traditional" looking menu. By simply changing our script 
we can create more creative menus, providing popup, pulldown, and nesting 
capabilities. Change your "menu.dts" script to look like the script below and re- 
run the menu program. BUT WAIT. You don't think we would make you do all 
this grunt work for the sake of an exercise. See the file "ex_menus.dts" on your 
disk. Use this file instead of doing all that editing. You could simply copy 

“ex _menus.dts" into "menu.dts" and then re-run the program. As you run the 

" menu, study the script to understand the definition. 


Before you study this script, a conceptual understaing of pop-up and pull-down 
menus is in order. d-tree regards pop-up and pull-down menus as simply 
another IMAGE. Because we want the cursor to travel between options, we have 
defined input fields on the image. These input fields are initilized with the 
"option’s text" by means of the DEFAULTS ability. We do not want the user to 
be able to change this text, so we have defined the input attribute of 
NOCHANGE for the fields. In some menus, we want the user to be allowed to 
enter the first letter of an option in order to GOTO that option. In this case we 
use the GOTO input attribute instead of NOCHANGE. We want this field to be 
highlighted when the cursor enters this field. The output attribute of INPUTRI 
handles this aspect. Frame characters (+) help as visual aids. The menu call 
criteria uses the "CURSOR = field" notation to determine selection. The HOOKS 
ability allows for menus to pop-up when the cursor enters a menu selection. 
See the menus ability in section 7 for more information. 


SPECIAL NOTE: As you may notice, input fields, used in this menu approach, 
are solely defined in the script without the use of the IFILS ability. They are not 
defined as hard coded variables in the program. The DODA containing these 
variables and their space is allocated at parse time, and is only done for the first 
IMAGE/FIELD definition in the script. Therefore, all input fields used in a menu 
script must be defined in the first IMAGE/FIELD definition, if you have not Hard 
coded a DODA or used the IFILS ability to define the DODA. Simply place the 
menu with the most input fields as your first IMAGE/FIELD definition in your 
script. This is only a limitation if variables are defined at runtime. If you hard 
code your own DODA or use the IFILS to define DODA, this does not apply. If 
this is confusing, define your DODA as hard coded or with IFILS ability. 


d-tree Reference Guide 2-63 


2.6 Menus - Tutorial 


ex_menus.dts 


IMAGEC menu) CINPUT_ADVANCE=CR} {BACKGROUND=BROWUN} {FORGROUND=BLACK} 


p— 


Frame. 
Title 


@DATE 


will be 
centered 


FIELDC menu) 

7* Symbol Name 
menul GOTO 
menuZ GOTO 
menu3 GOTO 


menu selection. 


DEFAULTS( menu) 

7* Symbol Name Type 
menul INIT 
menuZ INIT 
menu INIT 

HELPC( menu) 


7* Help Text or Token 
Do Your Daily Posting 
Goto Report Menu 
Describe Other Here 


MENUC menu) 
USES_IMAGE(C menu) 
7™ Call Criteria 
CURSOR=menul 
CURSOR=menuZ 
CURSOR=menu3 


Example: 
then call the menu named “menuZ2”. 


+Small Project Accounting 


Input Attribute 


Allous first character 
of menu option to be 
entered to GOTO that 


If cursor is on the “menul” 


@TIME 


=o 


System Master Menu Input fields 
for menu. Will 


be initilized 


with text by 
DEFAULTS ability 
below. 


+ 


Output Attribute Input Order */ 


AUTO_HELP INPUTRI 1 
AUTO_HELP INPUTRI 2 
AUTO_HELP INPUTRI 3 


Causes Associated HELP text to be displyed 
when cursor enters this field. Allous for 
tag along reference text for this type of 
menu. Notice message line when running menu. 


of defaults 


Defaults value */ 


Posting Menu 
Report Menu 


|} Menu option 
text. 


Other 
fields mf 
menul ——_—_______——-_|[Help text here 
menuZ is used as tag 
menu along text via 


the AUTO_HELP 


input attribute 


Type of Call Call Value 7 


MENUCALL menuZ 
MENUCALL menu3 
MENUCALL menu4 


input field when return is hit 


IMAGEC menuZ2) {LSTFLD_ADVANCE} 


@DATE Small Project Accounting System @TINE 
System Master Menu 
1. Customer Master Maintenance 4. Valid Account Codes Maintenance 
2. Project Master Maintenance S. Post Transactions 
3. Vendor Master Maintenance 6. Report Menu 
Select Desired Option: __ 
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MENUC menuZ) 
USES_IMAGE( menuZ) 

7m Call Criteria Type of Call Call Value */ 
menul=1 EXECL customex.exe —Emenu 
menul=2 EXECL pro ject —-Emenu 
menui=3 EXECL vendor —Emenu 
menul=4 EXECL account —Emenu 
menul=S EXECL posting —-Emenu 
menul=6 MENUCALL menu 


IMAGE(C menu3) CINPUT_ADVANCE=CR} {BACKGROUND=BLUE} {FORGROUND=RED} 
+ 


FIELD( menu3) 
7% Symbol Name Input Attribute Output Attribute Input Order */ 

menul NOCHANGE . INPUTRI 1 
menuZ NOCHANGE INPUTRI 2 
menu NOCHANGE INPUTRI 3 

DEFAULTS( menu3) 

_7* Symbol Name Type of defaults Defaults value 
menul INIT Customer Listing 
menuZ INIT Other Reports 
menu3 INIT Query Data 

HOOKS( menu3) 

7* Hook Symbol Name Condition Function Parameters “/ 


BEFORE_INPUT cur_image=menu3 AND cur_field=menul DT_IMGOT menu4 
AFTER_INPUT cur_image=menu3 AND cur_field=menuil DT_UNPOP menu4 


BEFORE_INPUT cur_image=menu3 AND cur_field=menuZ2 DT_IMGOT menuS 
AFTER_INPUT cur_image=menu3 AND cur_field=menuZ DT_UNPOP menuS 


Here we use the hook ability to provide POP_UP menus as the cursor enters 
a selection from “menu3". The first hook read as such: If the current 
image is “menu3” and the current field is “menul’ the do an image out 


function with image “menu4” before input, and after input unpop “menu”. 
We have not defined a hook for the third option on this menu. Uhen the 
user selected this option, “menu6" acts a a PULL-DOUN menu. 


MENUC menu3) 
USES_IMAGE( menu3) 
iA Call Criteria Type of Call Call Value */ 
CURSOR=menul MENUCALL menu4 
CURSOR=menu2 MENUCALL menuS 


CURSOR=menu3 MENUCALL menu6 
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IMAGEC menu4) CINPUT_ADVANCE=CR} {BACKGROUND=BLUE} {FORGROUND=RED} CPOP_UP} 


Only display these sides of the 
iframe. The alternate frame type 
idefines what the sides of the frame 
|look like. 


+ {LEFT} {BOTTOM} {RIGHT} {FRAME_TYPE=3} 


CONST( menu4) 
i YELLOW BLACK 
FIELDC menu4) 

7* Symbol Name Input Attribute Output Attribute Input Order */ 
menul NOCHANGE INPUTRI 1 
mMenuZ NOCHANGE INPUTRI 2 
menu NOCHANGE INPUTRI 3 

DEFAULTS( menu4) 

7* Symbol Name Type of defaults Defaults value */ 
menul INIT PULL 
menuZ INIT THIS 
menus INIT DOUN 

MENUC menu4) 

USES_IMAGEC menu4) 

7 Call Criteria Type of Call Call Value 7 
CURSOR=menul RETURN i 
CURSOR=menuZ RETURN Z 
CURSOR=menu3 RETURN a 


IMAGECmenuS) CINPUT_ADVANCE=CR} {BACKGROUND=BLUE} {FORGROUND=RED} {POP_UP} 


CLEFT} {BOTTOM} {RIGHT} {FRAME_TYPE=3} 


CONST menuS) 
1 YELLOW BLACK 


FIELD( menuS) 
“¥% Symbol Name Input Attribute Output Attribute Input Order */ 


OR 
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menul NOCHANGE INPUTRI 1 
menuZ NOCHANGE INPUTRI 2 
menu NOCHANGE INPUTRI 3 
DEFAULTS( menuS) 
7* Symbol Name Type of defaults Defaults value */ 
menul INIT Report 1 
menuZ INIT Report 2 
menu INIT Report 3 
MENUC menuS) 
USES_IMAGE(C menuS) 

7% Call Criteria Type of Call Call Value »*/ 
CURSOR=menul RETURN 1 
CURSOR=menuZ RETURN Z 
CURSOR=menu3 RETURN 3 


IMAGECmenu6) {INPUT_ADVANCE=CR} {BACKGROUND=BLUE} {FORGROUND=RED} {POP_UP} 


{LEFT} {BOTTOM} {RIGHT} {(FRAME_TYPE=3} 


CONST( menu6) 
1 YELLOW BLACK 
FIELD( menu6) 
7% Symbol Name Input Attribute Output Attribute Input Order */ 
menul NOCHANGE INPUTRI 1 
menuZ NOCHANGE INPUTRI yA 


DEFAULTS( menu6é ) 

7% Symbol Name Type of defaults Defaults value */% 
menul INIT Query 1 
menuZ INIT Query 2 


MENUC menu6é ) 
USES_IMAGE( menu6) 
7 Call Criteria Type of Call Call Value */ 
CURSOR=nenul RETURN 1 
CURSOR=menuZ RETURN yA 
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THE CATALOG 


3.1 CATALOG - Introduction 


The catalog program is a powerful utility built using d-tree functions and 
abilities. The catalog (dtcatlog) provides data, index, program, relationships, and 
ability dictionaries which aid in the management of application development. Be- 
sides providing an "instant" maintenance capability for any data file defined in 
the data dictionary, the catalog provides a variety of productivity aids such as 
automatically generating C record structures, DODA structures, as well as 
"start-up" r-tree and d-tree scripts. This section acts as a "user’s operation 
guide" to the catalog program while providing some technical insight. It as- 
sumes that the catalog program has been compiled, and the "validation file" 
(dt_catvd) used by the catalog has been loaded with the necessary codes. 
These codes are loaded when the import option is selected from the dt_catvd 
program as described in the COMPLETE THE INSTALLATION discussion in sec- 
tion 1. 


Let's start with a technical look at the catalog. The catalog program is simply a 
maintenance program written with the d-tree tools. It maintains a specific group 
of c-tree files which we have called dictionaries. These dictionaries provide a 
place where we can store definition information for files, fields, Indexs, index seg- 
ments, programs, and abilities, as well as how each of these entities relate to 
each other. The illustration below presents these dictionaries. The code where 
these definitions can be found is in "dtcatdef.h" and "dtcatlog.h". Using typdefs 
to define these file layouts is intended to ease the chore of modifying to these 
definitions if the user cares to define additional information. 


TABLE DICTIONARY (Cdt_cattd. dat) 
File Information 


typedef struct dt_cattd ¢ 
LF EL td_def: file definition */ 
TEXT td_filCDTCFILLNI: file name 7 


TEXT td_version(DTVERLEN]: version number a7 

UCOUNT td_colun:; number of columns*/ 

TEAT td_desc(€DTCDECLNI: file description */ 

TEXT td_system(€ DTCSYSLN); system name a7 

TEXT td_flag(2]; select flag m7 

TEXT td_type(€DTCFILLN]: file type m/ 
+ DT_CATTD;: 
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COLUMN DICTIONARY (dt_catcd.txt) 
Field Information 


typedef struct dt_catcd ¢ 
TEXT cd_fil€DTCFILLNI; file name 
TEXT cd_version{€DTVERLEN]:;: version number 
UCOUNT cd_fldseq: field seq number 
UCOUNT cd_dec;: number of decimals 
COUNT cd_fldtyp: field type 
COUNT cd_fldlen; field length 
TEXT cd_fldnam€DTCFLDLNI; field name 
TEXT cd_inpatr(81]; field input attr 
TEXT cd_outatr(8]: field output attr 
TEXT cd_descl DTCDECLN]; Field Description: 
TEXT cd_dfaltCDTCDECLN): Default Value: 
TEXT cd_vlen(€DTCDECLN]: Var len fld id 

+ DBT_CATCH: 


INDEX DICTIONARY (dt_catid. txt) 
Index information 


typedef struct dt_catid { 

IIDX id_def: index definition 

TEXT id_filCDTCFILLNI: file name 

TEXT id_version{€ DTVERLEN]): file version 

UCOUNT id_seq; index sequence 

TEXT id_idxfilCDTCFILLNI:; index file name 

COUNT id_members; no of index members 

COUNT id_ifilmod: index file mode 

UCOUNT id_ixtdsiz: index file ext size 

TEXT id_idxC€DTCIDXLNI:; index symbolic nane 
+} DT_CATID: 


SEGMENT DICTIONARY (dt_catsd. dat) 
Index Segment Information 


typedef struct dt_catsd { 

ISEG sd_def; index definition */ 
TEXT sd_filf€DTCFILLNI: file name «/ 
TEXT sd_version(€DTVERLEN]:; file version aS 
UCOUNT sd_seq; seg sequence 

TEXT sd_idxC€DTCIDXLNI: index name a7 
TEXT sd_col(€DTCFLDLN); column name “7 

} DT_CATSD;: 


PROGRAM DICTIONARY (dt_catpd. dat) 
Program Information 


typedef struct dt_catpd { 
TEXT pd_pgmnam( DTCFILLN]: program name 
TEXT pd_version(€ DTVERLEN]); program version 
TEXT pd_system[ DTCSYSLNI: program system name 
TEXT pd_desc(DTCDECLN]: program description 
TEXT pd_type( DTCFILLNI: program type 
LONG pd_stamp: unused 
COUNT pd_status;: unused 

+} DT_CATPD: 
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ABILITY DICTIONARY (dt_catad. dat) 
Ability Information 


This file is a c-tree variable length file where the entire record is 
considered variable length (no fixed length portion). It is used to 
store the parsed representation of abilities as they appear in 
memory. Ability definition stored in this dictionary can be “suapped” 
into memory when required, eliminating the necessity of a parse. 
Later in the documentation you will discover the pouer of “groups”, 
Where ability definitions can be “grouped” together and store ina 
file on disk. These definitions can then be “suapped’” in and out of 
memory. The ability dictionary can be looked at as the “group file” 
on disk for the catalog progran. 


RELATE DICTIONARY (dt_catrd. dat) ; 
Contains left and right pointers relating 
entries in the other dictionaries. 


typedef struct dt_catrd { 

COUNT rd_ldic; dictionary for entry 
POINTER rd_lrecno: left side record pointer 
COUNT rd_-ltype: left side record pointer 
COUNT Pa _ dic: dictionary for entry 
POINTER rd_rrecno: left side record pointer 
COUNT rd_rtype: left side record pointer 

+ DT_CATRD: 


VALIDATION DICTIONARY (dt_catud. dat) 


Simply a “look-up” or “validate” file used by the catalog 
program to verify this such as file modes, field types, etc. 


typedef struct dt_catud { 
TEXT vd_major(3); 7* validation major code 
COUNT vd_minor;: 7* validation minor code 
TEXT vd_desc(€DTCDECLN]; /“™ validation description 
COUNT vd_count: 7* validation numberic field 
TEXT vd_misc(€DTCFILLN]: “™ validation misc field 

+ DT_CATUD:;: 


Taking a glimpse at the internal files definitions will help define some of the exter- 
nal operations of the catalog program. Let’s execute the catalog program enter 
"dtcatlog" from the operating system prompt (shown here for DOS): 


C> dtcatlog 


The first time the catalog program is executed provokes the parsing of the d- 
tree script for the catalog program (dtcatlog.dts). Once this script is parsed, the 
definitions are stored in the ability dictionary, thus eliminating the necessity for 
parsing the next time this program is run. 


The catalog contains multiple menus and options. The options where 
“user operation" is obvious will not be addressed to allow us to focus on major 
“operation issues" of the catalog. 
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3.2 CATALOG - Data Dictionary 


The Data Dictionary maintains file, field and index definitions. The data diction- 
ary menu provides a means to add, change and delete these definitions. 
The following illustrates the data dictionary primary maintenance screen: 


Thu May 26 FairCom 28:21: 47 

File Name:[C File Description: 

Version Number: System Name: 

File Type: Extension: Mode: __ Rcd Len: Indexes: ___ 
Field Field First Vlen 
Name Type Description Field 


Sad 
© 
S 
om] 
© 
0 


——— 
———— ee 
Teme 
ee 
ee 
eee 
ee 
eee 
ee 
eee 
Se ee) 
eee ee 
eee 
Sen 
eee 
i 


Press ESC ESC to EXIT 


The following is a description of the fields on this entry screen. The screen ina 
combination fixed IMAGE followed by a "scrollable" SUBFILE. The fields main- 
tained in this fixed image belong to the TABLE (or file) DICTIONARY 
(dt_cattd.dat). Some entry fields have default values defined in the catalog’s d- 
tree script. Hitting the "default key" (shipped as the TAB character) will plug this 
default into the field. These fields are noted with "(default defined)" notation after 
the fields description. 


e File Name - is the name of this file as is resides on disk. An extension 
is optional. d-tree will use the extension define for c-tree’s incrementals 
if no extension is given. This extension can be found in the file “ctifil.h" 
in c-tree’s directory which is typically set to ".dat". 

e File Description - is a reference description to identify this file. 

e Version Number - identifies which version of this file this definition 
represents. Multiple versions of the same file may be maintained 
simultaneously. (default defined) 

e System Name - provides the means to group files by "system". Cross 
reference information "by system" may then be produced. (default 
defined) 


ne Ee eRe eT ey OT eT ee ee Pe Pe a 
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e File Type - The File Type acts as a work field for d-tree at program 
creation time. Simply hit the default key (TAB key) to default to 
"MASTER" type of file. This field aids d-tree is determining the kind of 
d-tree script specifications to write when the user selects this file at 
program creation time. Valid types are: 

MASTER - Primary file being maintained in the program; 

SFL - File is maintained in a subfile in the program. 

VAL - File is used to "validate" data in the program. 
See session 4 of the tutorial. This field will represent "how this file was 
used" the last time it was selected during program creation. (If this is 
confusing at this point in time, don’t worry, it will become clear as you 
run the catalog). (default defined) 

e Extension - The Extension represent the file extension length used by 
c-tree. See the c-tree documentaion for a complete description on file 
extension lengths. (default defined) 

e Mode - identifies the file mode used by c-tree 
(i.e. FIXED | VIRTUAL | SHARED). See the c-tree documentation for a 
complete discussion on file modes. Valid file modes may be obtained 
by entering a question mark (''?"). (default defined) 

e Rcd Len - The record length Is a protected field , calculated by the 
catalog which displays the number of bytes necessary for each record. 

e Indexes - identifies the number of Indexes defined for this file, is also 
protected, and is maintained by the catalog program. 


The following fields reside in the subfile portion of the screen and define the field 
definitions for the Column Dictionary (dt_catcd). 


e Field Name - is the symbolic (variable) name for the field. 

e Type - defines the type of field. Valid field types may be seen by 
entering a question mark ('?"). (default defined) 

e Len - defines the length of the field. 

e Dec - defines the number of decimal positions and pertains to floating 
field types only. 

e Field Description - provides a reference description for the field. 

e First Vien Field - identifies the first variable length field in this file. 
Enter ‘VL’ (only on one field) if this file is to be a variable length file. 
This field will then be considered to be the start of the variable length 
portion of each record. See variable length file support in the c-tree 
documentaion for more information on variable length files. 
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3.3 Catalog - INDEX DEFINITIONS 


Once the file and field information is entered, we can add the index definitions 
for the file. This is done by pressing F3 from this entry screen. The following 
index entry screen will appear: 


Key Definitions 
Key Key Key Dups Null Empty Index File 
Name Length Type Ok Key Char Mode Ext Name 
Ccustomeridx J] il N ¥ 32 1 48696 customer. idx 


Field Name Offset Length Mode 


key segments. 


Presented in this entry screen are two "scrollable" subfiles. The first, which is 
only displaying one subfile record at a time, defines the fields that make up the 
index definition. This is the information stored in the index dictionary 
(dt_catid.dat). Page-Up and Down will "scroll" this line allowing for additional 
index definitions. The following fields define the index: 


e Key Name - Symbolic reference name for this index used in both 
d-tree and r-tree scripts. 

e Key Length - Total Length of the key. This field is maintained for you 
by the program. 

e Key Type - c-tree’s key type which controls key aspects such as key 
compression and right-to-left-scan. Enter a (?) to select a valid key 
type. See the c-tree documentaion on key types for a further 
discussion. (default defined) 

e Dups OK- (Y/N) indicates if duplicate key entries are allowed. Note 
when (Y)es is entered the catalog takes care of the extra four (4) bytes 
in the key length required by c-tree. (default defined) 

e Null Key - (Y/N) indicates if an "index entry" , derived from a record, 
which is considered to be Null, should or should not be added to the 
index. The consideration to be Null is determined by the Empty 
Character definition below. (default defined) 


—_—_— eee 
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e Empty Char - If a "index entry" is made up of entirely this character it 
will be considered a Null index entry. This is used in conjuction with 
the Null Key Flag described above. This character must be represented 
as a decimal value. Set this value to 32 (space) for d-tree maintained 
files for d-tree initialized fields to blanks. (default defined) 

e Mode - Index file mode identifies the file mode used by c-tree (i.e. 
VIRTUAL | SHARED). See the c-tree documentation for a complete 
discussion on file modes. (default defined) 

e Index Ext - The Index Extension represent the file extension length 
used by c-tree for this index file. See the c-tree documentaion for a 
complete description on file extension lengths. (default defined) 

e Index File Name - is the name of the index file as it resides on the 
disk. The first index defined will always have an index file name. If the 
user leaves this field blank, the program will plug the name used for 
the data file with a ".idx" extension appended to the name. Each 
additional index may or may not have a disk file name. If an addition 
index definition is given a name, it will be treated as a seperate index 
file. This will restrict the use of this file definiton to be only used with 
parameter files. c-tree incremental file definition requires that all 
Indexes reside in one physical file as members. Leaving the addition 
Index disk file name blank will define this Index as a member within the 
previous "parent" Index. By "parent" we mean an index that did have a 
disk file name provided. 


The second subfile on this entry screen is used to define the index segments 
that make up an index entry. This subfile is a "child" subfile, who's "parent" is the 
index definition subfile just descibed above. Notice when you scroll the index 
definition subfile, how it’s child, the segment definition subfile, will scroll along 
with it. The "parent" subfile will not scroll when the "child" is scrolled. This illus- 
tates the power of d-tree’s subfile routines when working with hierarchies of sub- 
files. The following is a description of each input field in the segment definition 
subfile: 


e Field Name - the field symbolic name used to comprise this segment 
of the index. F8 will return you to the primary maintenance screen to 
see your field names. Then F3 again to return you to index definitions. 

e Offset - The offset within the field to start the index segment. This 
IS NOT the offset within the record itself as most c-tree user's are 
use to. The field name gives the catalog the offset within the record. 
This offset provides the flexablity to defined pieces of a field as a key 
segment. Consider the following: Given a six (6) byte string which is 
storing a date in MMDDYY format, we want to build an index over this 
file by this date. Proper key segment definitions require the date field to 
be defined twice, as two seperate segments. The first date segment 
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has offset four (4) with a length of two (2), while the second date 
segment has an offset of zero (0) with a length of four (4). This will 
construct a key in YYMMDD format. 

e Length - the number of bytes from the field to be used when 
constructing a key entry. 

e Mode - segment mode define segment trasformation when the key 
entry is constructed. See c-tree’s segment mode documentation for 
further discussing. 


Once the index information is entered pressing the "post" key (END key in DOS) 
will post this definition to the applicable dictionaries. 


3.4 Catalog - FUNCTION KEYS 
SUPPORTED WHEN VIEWING A DATA FILE DEFINITION 


e F1 -C Structure - d-tree will create a C data structure for the current 
file. Pressing the F1 key a second time provide a prompt to "dump" the 
created C data structure to a specified disk file. 


e Shift F1 - Import File Definition from an existing C structure - While 
viewing the Add Data Definition screen, press the key combination 
Shift F1. A small pop-up window will be presented at the bottom of the 
screen. 


Import File definition from C Structure 
File: [€ ] First Field: 


Tag/No: Last Field: Append Def( Y/N): __ 


This feature will allow you to import data definitions from existing C 
structures residing in source files. You may import all or any portion of 
the C structure. You may overwrite the current file’s data definition or 
append the imported information to it. The following is a description of 
each field presented on the Shift F1 pop-up window: 


Source File - Enter the full name (including extension) of the C source 
file containing the data structure. 


Struct Tag/No - Enter the structure tag name (token following the 
word 'struct’) associated with the structure to be used or the oc- 
curence number of the structure as it is found in the source file. d-tree 
determines if the value entered is a tag name or occurence number by 
performing an ASCII to integer conversion on the entry. If the resulting 
value is greater than 0, the entry is considered to be a structure num- 
ber otherwise, it is considered to be a tag name. 


| 
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First Field - (optional) Enter the first field within the structure to be 
retrieved. 


Last Field - (optional) Enter the last field within the structure to be 
retrieved. 


Append Def (Y/N) - Should the new data definition information 
retrieved from this C source structure be appended to the current file 
definition displayed on the screen or should this information replace 

_ the current definition? Enter (Y)es to append it to the current definition 
or (N)o to overwrite the current definition. 


e F2 - Create DODA - d-tree will create a DODA for the current file. 
Hitting F2 again will provide a prompt to "dump" this definition to disk. 


e Shift F2 - Import from DODA Source Specs - This function displays a 
similar screen to the one shown above for the SHIFT F1 option. This 
function provides the same ability except allows this import of data file 
definition to come from an existing DODA. 


e F4 - Parameter File - create a c-tree parameter file for the current data 
file. 


e F4 F4 - Dump Parameter File To Disk - Generate Maintenance 
Program Pressing F4 a second time presents the following pop-up 
menu prompting for the necessary information to "dump" the 
parameter file just created to disk and build a standard 
Add/Change/Delete/Print maintenance program over the current data 
file using the newly created parameter file specifications. 


Dump Specs to Disk 
This option will dump the file specifications you are viewing to disk. 
Key in the source file name of your choice WITHOUT an extension. 
The file name extension will default. A “.p” extention is used when 
vieuing parameter files. A ".h” extension is used for incremental 
structures. A °Y’ for the create option results in an additional “.c” 
source file to be created for a standard maintenance program. 


Name of Source File(s):C JDo you want to Create Program Source: __ 


Source Filename - The source filename field is the file which will con- 
tain the parameter file data. DO NOT specify a file extension. The file 
extension ’.p’ will be assigned. 

Create Program Source - A reply of ‘Y’ in this field will prompt d-tree 
to create a standard Add/Change/Delete maintenance program using 
the parameter file being dumped to disk. Both the C source and d-tree 
script are generated. 
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e F5 Incremental Structures - d-tree will create a c-tree incremental 
structure for the current file. 


e@ F5 F5 - Dump Incremental Structure to Disk - Generate Maintenance 
Program Pressing F5 a second time presents a pop-up menu 
prompting for the necessary information to build a standard 
Add/Change/Delete/Print maintenance program over the current data Ww 
file using c-tree’s incremental file approach. This prompt acts the same 
as the prompt described above for F4 F4. 


e F6 - Instant Maintenance - the catalog provides “instant maintenance’ 
over any file defined in the data dictionary. Simply hit the F6 key while 
viewing a file definition and the catalog program will build a default 
d-tree script for this file. It will then parse this script, converting the 
catalog mainline into a standard ADD/CHANGE/DELETE maintenance 
program for the file selected. 


e F7 - Unused 


e F8 - Return to Data Definition Screen from other screens or windows 
presented when other function keys are pressed. 


e F9 - Delete A Subfile Record - By pressing F9 when the cursor is 
positioned in a subfile record will delete that record from the subfile. ~ 


e F10 - Insert a record into a subfile - pressing F10 when positioned 
within a subfile will cause a blank subfile record to be inserted before 
the current field definition entry. All subsequent subfile records will be 
shifted down one line. 
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3.5 View/Modify Data Dictionary Definition - 


The View/Modify selection provides the capability of randomly viewing and/or 
editing a file definition. After selecting the View/Modify selection d-tree presents 
a prompt screen containing three possible means of selecting a Data Dictionary 
entry. 


airlom 
Data Dictionary 


Enter File Name: 
or 

Enter File Desc: 
or 

Enter File System: 


From this prompt the user can proceed to select the file desired. 


Data Dictionary 

Name Version Description System 

account : Account Code File Small Project Acct. 
customer ‘ customer IMPORTED 

dist ; Distribution File Small Project Acct. 
project ‘ project IMPORTED 

trans . Transaction Master File Small Project Acct. 
vendor : Vendor Master File Small Project Acct. 


Enter Desired Option:C__J 


Press ESC ESC to EXIT 


If the users makes changes to the file definition, the catalog checks to see if any 
critical information related to a file’s definition (i.e. filename, field lengths, ver- 
sion, etc) has been changed. If so, the following prompt is displayed: 


File Definition Has Been Changed 


Is this a (NJeu version of the file 7 

If so the old version will be preserved. 
or 

Does this (Replace the old definition 7 

If so old definition WILL BE LOST. 


CNJeu or (Replace :C€__] 
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The user has the option to either make a new file definition while retaining the 
old or to replace the old definition with the new. Using this feature, multiple ver- 
sions of the same file may be maintained simultaneously. This could prove to be 
useful in supporting a commercial application with multiple releases. If (N)ew is 
entered a new version of the file is created, provided a new version number has 
been entered. If (R)eplace is entered, the following screen will be presented: 


WwW 
| Tue Jul 26 FairCom 69:85:59 
| File Reformatting Utility 
The Old File Definition is Will Be REPLACED. 
The file format facility requires both the old and the neu file 
layouts. If you want to take advantage of the file reformat 
facility one of the follouing actions must be selected: 
{_JReformat the following file in place. 
_ Create a stand alone executable to be used for 
reformatting at a later time. Program Name: 
Old File Name: 
Neu File Name: 
Place a ’Y’ in desired option(s) then 
Hit POST key to continue. 
Copyright 1988 FairCom 
Press ESC ESC to CANCEL REPLACE 
Ww 
Because the old file definition is being replaced, the user is given two reformat- 
ting options. File reformatting requires both the old and the new file definitions. 
Because the old file definition will be lost by this replace option the following Op- 
tions are provided: 
e Reformat in place - This will cause the catalog to look in the current 
directory for the file for which you just made the change. If found , will 
reformat the file in place, followed by an index rebuild. By reformat we 
mean will physically move the existing data in the file to fit the new file 
definition. 
e Generate a stand-alone reformat program which may be executed at 
a later time. This method is very useful if you do not have immediate 
access to the data file to be converted. This program can also be used 
to send to your customer along with your update to allow them to 
reformat their data files. 
Ww 
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3.6 Catalog - Reformat 


Mon Apr 28 FairCom 
System Catalog 


aster Menu 
Data Dictionary 
Program Dictionary 
Relate Dictionary 
Execute Compile Que 
Clear Compile Que 
Catalog Reports 
Return to OS 


FairCom (c) 1988 


The Reformat selection provides a way to reformat between two versions of the 
same file define in the data dictlonary. After entering the file name from the 
prompt screen the catalog will present the files on a select screen shown below: 


Wed Jul 27 FairConm 69:43:58 
File Reformatting Utility 
Sel File Type Name Version Description System 
account Account Code File Small Project Ac 
account Account Code File Small Project Ac 
customer customer IMPORTED 
customer customer SPAS 
dist Distribution File Small Project Ac 
project project IMPORTED 
project project IMPORTED 
trans Transaction Master File Small Project Ac 
ucs_invun.dat UCS Inventory Master UCS PROCESSING 
Vendor Master File Small Project Ac 


Pe al ae Se ee 
Oooodea © ® © & ® 


vendor 


From File Entry 


[ro File Entry 


Entering an 'F’ in front of the "FROM" file an a 'T’ in front of the "TO" file. Press 
the POST’ key (END key in DOS). A comparison of the two files is done, 
follwed by the reformat. 
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3.7 Catalog - Select File 


Mon Apr 26:16:07 


aster Menu 
Data Dictionary = Ww 
Program Dictionary 
Relate Dictionary 
Execute Compile Que 
Clear Compile Que 
Catalog Reports 
Return to OS 


The select files option provides a means to create a variety of source specifica- 
tions used in d-tree, c-tree and r-tree development. It major advantage is that it 
allows you to select many files at a time. Once this option is selected the follow- 
ing screen is presented: 


Thu May 26 FairCom 21: 46: 44 
System Catalog 
Select a Group of Files ~~ 


Select the Desired Source Specs to Create 


C_ 3] Create a Parameter File 

Create C Source Structures 

Create a Data Object Def Array (DODA) 
Create Incremental Structures 

Create a d-tree Script 

Create a r-tree Script 


Enter Source File Name: 


Do you want to make an entry into the Program Dictionary: __ 


Press ESC ESC to EXIT 


To select any of the options on the Select File screen, type a 'Y’ in the blank 
preceding the option. Yo 


—_— 
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e Parameter File - will build a c-tree parameter file. 

e C Source Structures - will build the C language data structures. 

e Data Object Definition Array (DODA) - will build a DODA structure. 

e Incremental Structures - will build the c-tree incremental data 
structures. 

e d-tree Script - will build a d-tree script with various ability cefinition 
sections depending upon the purpose of each file selected. 

e r-tree Script - will build a default r-tree script. 

e Source File Name - will be the name used by d-tree for the files which 
shall contain the generated source information. Each file will be 
uniquely identified by its related file extension. For example, Parameter 
files ’.p’, C source files ’.c’, d-tree script files ‘.dts’ and r-tree script files 
US 

e Program Dictionary- An entry of ‘Y’ will direct d-tree to prompt for an 
entry into the Program Dictionary. It will also cause a ".c" mainline 
routine to be created based on the program type entered below. 

e Program Type - Enter one of the valid program types to tell the 
catalog the type of mainline to create. 


After completing entry on this screen press the ‘POST’ key. d- tree will respond 
by displaying a file selectlon screen. To select multiple files to be used In the 
source and script files, place a number or letter in the adjacent ‘Sel’ field which 
corresponds to the order in which you would have the files appear. This selec- 
tion process is illustrated below. 


Data Dictionary 
Name Version Description System 

VAL account Account Code File Small Project Ac 

VAL account Account Code File Small Project Ac 

VAL custormer customer IMPORTED 

MASTER customer customer SPAS 

SFL dist Distribution File Small Project Ac 

VAL project project IMPORTED 

VAL project project IMPORTED 

VAL trans Transaction Master File Small Project Ac 
C_JMASTER ucs_invn.dat UCS Inventory Master UCS PROCESSING 
— VAL vendor Vendor Master File Small Project Ac 


i 
Z. 
Lis 
Zs 
or 
i. 
ra 
A. 
A. 
ee 
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For purposes of creating the d-tree script you may also specify how each file is 
intended to be used in the program. Valid entries are MASTER (primary file to 
be maintained), SFL (subfile), and VAL (validate). This will control the specifica- 
tion written in the d-tree script. A full example of running this option is illustrated 
in session 4 of the tutorial. 
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3.8 Text Out/Text Out 


The "Text Out" selection will dump the data in the catalog dictionaries to cor- 
responding ASCIl files. These files have the same names as the data files execpt 
with a ".txt" extension (i.e. dt_cattd.txt). The "Text In" selection will load all the 
dictionary files from their corresponding ASCII files. An excellent application of 
the "Text Out" and "Text In" selections would be to use them to port the diction- 
ary data from one operating system environment to another where the binary 
data files are not compatible. (Such as from an MS-DOS based machine to a 
UNIX environment.) 


3.9 Program Dictionary 


The program dictionary options allow for standard maintenance over the diction- 
ary file dt_catpd.dat. This file is used as a program reference file used by the 
catalog reports for cross reference information. Maintenance options allow for 
ADD/CHANGE/DELETE capability to program definitions. Entries are made into 
this file for programs that are created through the catalog. 


IMPORT PGM - The import program option is provided to import file definitions 
that have been prototyped with d-tree’s "run" program. 

THIS OPTION IS ONLY INTENDED FOR d-tree SCRIPTS THAT WERE 
CREATED BY THE "RUN" PROGRAM. See session 3 in the tutorial for illusta- 
tion of this import capability. Enter the filename of an existing d-tree script. The 
file extension ".dts" is assumed. 


3.10 Relate Dictionary 


The purpose of the Relate Dictionary is to maintain relationship definitions be- 
tween programs, data files and d-tree abilities. The current version of the 

Catalog only permits viewing entries from this menu selection. The concept of re- 
late maintenance will evolve in future realeases of d-tree. 
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3.11 Compile Que 


d-tree provides a handy feature within the catalog which permits the user to ac- 
cumlate programs to be compiled at one time. The compile que is nothing more 
that a text file with a list of program names. When a program is submitted to the 
compile que, it’s name is simply appened to this file. When the execute compile 
que option is selected the program called dt_doque is called which reads this 
que file and compiles each program name found. The header file dt_compl.h 
shown below defines elements used by this process: 


Satine SR SR a a dt_compl.h 

7* batch file compile definitions */ 

udefine DTCOMPILE “compile. bat” 7% program compile batch file */ 

udefine DTCATQUE “dtcompil. que” “* compile que file */ 

tdefine DTPQNAME “dt _doque. exe” 7% process compile que program name */ 

rdefine DTCOMP_P ‘“‘dtcomp_p. bat” 7* batch file for “run” pgm -c compile 
option-parameter files pgm */7 

udefine DTCOMP_I ““dtcomp_i.bat”’ “™* batch file for “run” pgm -c compile 

option-incremental files pgm */Z 


Clear Compile Que - this option simply deletes the text file defined above that is 
used as the compile que. 


3.12 Catalog Reports - 


The catalog report option displays various reports that are available from infor- 
mation posted to the dictionary. Run each report once you have data in you 
catalog. 
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4.1 Basic Interpreted Screen 1/O 


You have seen some examples of productivity provided by d-tree while creating 
applications using "run" and the "catalog" program in the tutorial. The true 
power of d-tree lies within the toolbox of functions provided to build applica- 
tions. This is made evident through the fact that the bulk of this manual is the 
description of individual functions. 


The developer who discovers the power and flexibility of the d-tree tools, by effi- 
ciently assembling them together, will get the most oui of d-tree. Both the "run" 
and "catalog" programs are examples of dynamic modules, being redefined at 
runtime, which were built using the tools. 


The purpose of this section Is to instruct you in the requirements and guide you 
in the construction of useful function calls. To illustrate these requirements and 
concepts we will be working with a series of example mainline modules. Each 
example module will illustrate functions which provide various capabilities. The 
first example module will outline the minimum requirements, while successive 
modules will present more in-depth examples of time-saving tools. 


ADAM - Before we actually proceed through each example we must first estab- 
lish the definition of a new term, Ability Definition Allocated Memory block 
(ADAM). A d-tree ADAM is, as its name describes, an allocated block of 
memory, static or dynamic, which contains definition utilized to perform abilities. 
An ABILITY is an activity performed by a program for a certain purpose. As you 
will discover, the user has the means to add his own abilities to d-tree. For ex- 
ample, the ability to screen I/O, interpret keystrokes, or manipulate data, may all 
be considered abilities. In order for the user’s program to perform an ability, 
there is one or more functions that must be called relating to that ability. These 
object definitons (also referred to as Ability Definitions) are contained in ADAMs. 


Let's take an example: We need the ability to project a screen out to the user. 
In order to project the screen we will need its definiton. By defining a typedef as 
a structure, we can define the fields within the structure that we would need to 
define this screen (coordinates, attributes, etc.). Then, given an allocated 
memory block that has been initialized with the screen's definiton (the IMAGE 
ADAM), we can provide functions to perform the screen output, passing a 
pointer to the definition structure, giving the function its required definition. 
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d-tree ABILITY - The term ability can be used in many contexts. For clarity we 
will outline what constitutes a d-tree "Ability". 


@ An "Ability" is an activity to be performed by a program for a particular 
purpose. (ie: screen I/O) 

e An "Ability" is given a reference name. (ie: IMAGE). 

@ An "Ability" is assigned a reference number in DT_DEFIN.H. 
(ie: DTKIMAGE) 

e An "Ability" definition typedef is defined in DT TYPDF.H to contain the 
definition of objects necessary to perform the ability. (ie: DTTIMAGE) 

@ An "Ability" requires an initialized ADAM containing definitions of its 
related objects 

e An "Ability" has a d-tree script interface syntax definition. 
(ie: IMAGE(master) ) 

e An "Ability" has a parsing function which is used to convert its script 
definition into an ADAM. (ie: DTPIMAGE) 

e An "Ability" has related function calls to perform its objectives which 
use a pointer to the ability’s ADAM for required definition. 
(ie: DT_IMAGE, DT_IMGOT, DT_IMGIN). 


There are at least three (3) ways to create an ADAM, or in other words, to initial- 
ize the allocated memory with the "Ability" definition. 
e Interpretive 
The "Ability" definition, in script form, may be initialized into allocated 
memory by a parsing function. Let’s use the keyboard "Ability" as an 
example. A terminal definition, as in the "termcap" file, is considered to 
be in d-tree script form defining your terminal’s specific 
characteristics. When the keyboard’s parsing function (DT KEYBD) is 
called, memory is dynamically allocated and initialized with the 
keyboard defintion. This allocated block of definition is referred to as 
the keyboard "Ability’’s ADAM. 


Hard Code 

The "Ability"’s definition may be hard coded into the source code, 
either ii the mainline or included in a header file, and compiled into the 
executable. Static memory is allocated then initialized with the ability 
definition at run time. This method restricts changing "Ability" definition 
somewhat, although it does provide smaller executable code as well as 
faster startup time, because the parsing functions are not necessary in 
the code and are not executed. 


—_——————— eee 
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e Dictionary Initialization 
An ADAM can be stored in a c-tree variable length data file just as they 
are used in the catalog program. This data file is referred to as an 
(ADAM) Dictionary (the ability dictionary is simply an ADAM dictionary 
used by the catalog program). The group functions (DT_GPOUT and 
DT_GPINN) are powerful ways of swapping ADAM definitions in and 
out of memory. See group functions for more detail. 


Let’s continue with our first example and take a closer look at initializing ADAMs 
via the interpreted method. 


NOTE: It is recommended that you either print or view the files used in the fol- 
lowing discussions. 


EX IMAGE 


The first example mainline module we will be using is the program 
EX_IMAGE.C. With this module we will describe the minimal requirements for 
using any d-tree tools as well as illustrate the screen and keyboard I/O facilities. 


At this time either print a hardcopy of the file "ex_image.c" and "ex_image.dts" or 
load them into your text editor when necessary to follow along as we explain 
the various d-tree tools used In it. 


The first significant items are the Include statements. 


#include "DT DEFIN.H" - ability definitions 
#include "DT _GLOBL.H" - global variables 


The header files DT DEFIN.H and DT_GLOBL.H are both required for any 
modules using d- tree functions. 


The next section you will see is simply a series of user field definitions. These 
are ordinary field definitions which will be used in this particular program. 


The following section is called a DODA, Data Object Definition Array. Due to the 
script interface used by d-tree ,any program using the tools to manage data 
must have a DODA. A DODA is simply a table of fields with symbolic names, 
their associated addresses, the field types and the length of the fields. (DODAs 
are also described in the r-tree Reference Manual.) 


The next section is an array of type DTTHRDCD, d-tree hard coded. ADAMs 
can be initialized in static memory by hard coding the specifications into the 
source of the program. In our example we are hard coding a DODA into the 
program. The table DTSHRD01, of type DTTHRDCD, is a list of ADAMs that are 
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hard coded in this source file. This is required for any d-tree specification that is 
hard coded. As we progress into the example this concept of "interpreted" as op- 
posed to "hard coded" definitions will become more clear. 


The hard coded table of type DITHRDCD must contain the following entries for 
each "Ability" definition that is hard coded. 


e The address of the "Ability" definition table. It is possible to have 
multiple source files with multiple hard coded "Ability" definitions. In 
order for a hard code table to reconcile the address of the "Ability’ 
definition, this definition must reside in the same source file as the hard 
coded table (the DTTHRDCD table) or be defined as an extern. 


e The reference number (from DT_DEFIN.H) for this "Ability" definition. 
(ie: DIKDDODA) 


e The number of "Ability" definition occurences in this hard coded 
definition. (ie: number of DODA entries.) This can be coded as: the 
sizeof the definition table divided by the sizeof the typedef 
associated with this "Ability" definition. 


Since we can have multiple source files, each containing a table of hard coded 
ADAMs, we must have an additional array, in one of the source files, containing 
pointers to the hard coded tables. This table must be of type pointer to 
DTTHRDCD and must be named DTSHRDCD. See below. 


DTTHRDCD *DTSHRDCD[DTHRDCD)) = { 
DTSHRDO1, /* first hard code table */ 
DTSHRDO2, /* second hard coded table */ 


} 


Note: this illustration shows two hard coded tables. If only one is present the 
second pointer should be replaced with a null pointer such as (DTTHRDCD *)o. 
Also note, there is a #define in DT_GLOBL.H defining DTHRDCD as 2. This 
limits the number of separate source files that can contain hard coded d-tree 
"Abilitys to two. To increase this simply change the #define. 
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As a brief review, we have seen that in any C program using d- tree tools you 
must have: 
e The following include files: 
#include "DT _DEFIN.H" 
#include "DT GLOBL.H" 
e user data definitions 
e DODA - defining data files (hard coded or interpreted) 
@ an array of type DTTHRDCD listing all hard coded "Abilitys". (optional) 
@ an array of type *DTTHRDCD[DTHRDCD] containing pointers to all 
DTTHRDCD arrays defining hard coded "Ability's. (optional) 


The following section is main(argc, argv). Note that the first function called is the 
getenv() function. This is a system function which should be supported by your 
system. If not, replace it with the appropriate function for your particular system. 
The next items are simply work fields which will be used later in the program. 


The first thing which must be done in the main(Q) portion of any program is to 
issue a call to DT_SETTY(1) to initialize d-tree. DT_SETTY(0) must be called at — 
the end of each program to deinitialize The function DT_SETTY initializes 1/O 
protocol as well as assigns structure pointers utillzed by d-tree. 


Before we may perform screen I/O we must first inform the program of the ter- 
minal and keyboard characteristics. This ls accomplished via the "termcap" file. 
The function DT_KEYBD Is passed the "termcap" file name along with the ter- 
minal identifier. This function will read the "termcap" file, looking for the desired 
terminal. Once found, it will initialize this program to that terminal's characteris- 
tics. Note the use of the DT _KEYBD function, here we are using the getenv func- 
tion to get the terminal name. 


In this example we are performing screen I/O. Our screens are painted in the file 
"ex _image.dts". Before they may be used they must first be parsed into allo- 
cated blocks of memory. A call to DT PARSE passing it the screen name ,will 
result in the parsing of your screen. Syntax errors in the d-tree script will be 
detected. Refer to the error message guide to resolve any errors. 


The next statement, the switch statement, illustrates the DT_IMAGE function. In 
our example we are passing it the value of '1’, this is the identifier of the screen, 
IMAGE(1), in our script. The DT_IMAGE function displays the screen and ac- 
cepts input from all the fields. The printf’s following the function call illustrate the 
recognition of various keystrokes established in the "termcap" file by the ter- 
minal definition, as well as data that has been accepted. 


Note here that we used a screen number (1). In a d-tree script a name may also 
be used (ie: “master'). The image function calls like DT IMAGE require an image 


d-tree Reference Guide 4-5 


4.1 Basic Interpreted Screen I/O 


number. When a name is used in a script instead of a number, d-tree assigns a 
unique number to that name. This unique number can be accessed within a 
program with the DT_INAME function. 


Let's assume we had painted our screen in "ex_image.dts" as 
IMAGE ("master') 

instead of 

IMAGE(1) 

We then could replace 

switch (kbd =DT_IMAGE(1)) 

with 

switch (kbd = DT_IMAGE(DT_INAME("master'))) 


As noted above we, call DT_SETTY(0) at the end of every program, followed by 
the exit call. 


This is an example of some basic screen I/O using the d-tree tools. We will 
build on this as we continue to discover the tools. 


At this time compile and execute the example program "ex_image.c". 
NOTE: While the use of the "termcap’ file is still fresh in your mind, it is recom- 


mended that you review the TERMCAP section of the Reference Manual at this 
time. 
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4.2 Interpreted to Hard Coded Conversion 


"Bridging From Interpretive To Hard Coded Entity Definitions" 
In the previous session we touched on the concepts of interpretive and hard 
coded ADAM definitions. A good example of an interpretive definition was the 
screen that was painted in our d-tree script file, read by the parse function and 
stored in dynamically allocated memory. On the other hand, the DODA defini- 
tion was hard coded into the C source file and the necessary tables for hard 
coded defintions were present. 


Using the interpretive method to build screens is extremely useful during applica- 
tion development. This provides the flexibility of easily modifying the appearance 
of a screen, and simply re-parsing, generating instant results. However this does 
require the additional overhead of parsing. 


In this session we will discover how to use the d-tree tools to build the bridge 
from interpretive to hard coded definitions. This capability will provide smaller 
code as well as Increased startup time when the program is executed, because 
parsing is not necessary. It also allows finished programs to be sent to users 
without scripts. 


By simply adding the function DT COMPL (d-tree compile) to our C source file 
("ex_Image.c"), d-tree will create the C source representation of the script 
(“ex_image.dts") in hard coded form. This hard coded definition is placed in a 
header file name passed to the function. This function must be placed after the 
parse function in your C source code, for it Is this parsed definition that it is writ- 
ten to disk. 


Place this function in the source file "ex_image.c" just before the final 
DT SETTY(0) function call as demonstrated below. 


ex_image.c 


case DTKBPU: printf(*’page up was hit’); 
break: 


case DTKBPD: printf ("*page doun was hit’): 
break: 

default: 
break: 

+ 7* end suitch 7 


“7* now lets check some data to see if the input worked */ 
printf£(’Number=“%d"", number); 
printf£("Name= “Zs"’,Name); 


if ©DT_COMPL("’ex_image.h")) insert function here. 
printf("Could not Write Co 


mpile specs\n"’); 


DT_SETTY(@): 


exit(@); 
} 
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Note that the parameter being passed to DT_COMPL is "ex _image.h". This will 
be the name of the include file which will contain the parsed script definitions. 


Now we must re-compile "ex_image.c" and after a successful compile, execute 

the program. Nothing obvious will be apparent upon program execution. View 

the new header file "ex_image.h". This header file was just created by our | 
program with the DT_COMPL function. You will notice the screen and other 4 
ADAMs parsed in by DT_PARSE are now residing in this header file as C source 

code. A table of all the hard coded ADAM’s in this source file has also been 

created. (ODTSHRD02). DT_COMPL has also provided the pointer table, for all 

hard code tables. Note that this pointer table contains an entry for the original 

table from the source file "ex_image.c" (DTSHRD01), and one for the new table 

from the current header file (DTSHRD0O2). 


Now that d-tree has created a header file containing the C source code for 
ADAMs which were previously interpreted via the parse routine, we can now in- 
clude this header file in our program to replace many previously necessary func- 
tions. To illustrate how the source code would now appear including this new 
header file, view or print the source file "ex_img2.c". Follow along as we com- 
pare the differences in this source code and that of our previous "ex_image.c' 
file. (hard code vs. interpretive definitions.) 


You will notice the array of pointers to hard coded entity tables has been 

removed from this source file and placed in the header file. The table in the new ~ 
header file also now contains an entry for the new table of hard coded defini- 

tions within that same header file. 

The include statement 

#include "ex_image.h 

has been added to include the header file containing all the hard coded ADAMs 

created by DT_COMPL. The file to be included must be the same as that 

passed to the function DT_ COMPL. 


Note that the function DT SETTY(1) must still be called to perform program 
initialization. 


The keyboard definition is now also hard coded. Therefore, we must call 
DTPKEYST to inform the program that the definition is hard coded. This function 
is ONLY called when you have a hard coded keyboard definition. (don’t worry, 
the next sections show hard coded screens with interpreted keyboard) 


In brief, if your keyboard definition is NOT hard coded you must issue a call to Y 
DT_KEYBD passing it the "termcap" file name and the terminal name to search 

for within the "termcap" file. If the keyboard definition IS hard coded you must 

issue a Call to the function DTPKEYST. 
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Since all of our ADAMs are now hard coded, it is no longer necessary to per- 
form the parsing routine. Thus it has been removed. However, we do need to es- 
tablish some pointer relationships between the definitions prior to using them. 
This is accomplished by the set pointers function. (DT SPTRS). The rest of the 
program is the same (except we are not calling DT_ COMPL). 

Within our program you will notice that there are three (3) basic areas of 
initialization: 


e Program Initialization - DT_SETTY(1) 
This is required at the beginning of any program using d- tree 
functions. This function sets 1/O protocol as well as global variables 
pertaining to the ADAMs. 


e Keyboard Initialization - DT KEYBD or DTIPKEYST 
lf the definition is to be parsed, the function DT_KEYBD will retrieve the 
terminal definition from the TERMCAP file. 
If the definition is hard coded, the function DTPKEYST must be called 
in order for the program to recognize the hard coded definition. 


e Ability Definitions - DT_PARSE or DT SPTRS 
If the definition Is to be interpreted, DT PARSE must be called to 
interpret the d-tree script and create ADAMs in dynamically allocated 
memory. 
If the ADAMs are hard coded, the function DT _SPTRS must be called 
to establish pointers to these hard coded definitions. 


Note: The following section will illustrate mixing hard coded definitions with 
those that are interpreted. 
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4.3 Combination Interpreted & Hard Coded 


In our first example we learned how to define ADAMs by interpreting them at 
run time. In the next example we learned how to use the DT COMPL function to 
hard code these definitions into a header file and include them at compile time. 
In this session we will discover how to use a mixture of definition methods 
within the same program. Specifically we will interpret the keyboard definition 
while leaving all the other ADAMs hard coded as in example two. 


First, let’s outline the general flow of any d-tree parsing function: 


e 1. Count the mandatory occurences for each "Ability" definition 
encountered. 

e 2. Dynamically allocate a block of memory of the “Ability"’s type for the 
number of occurences counted. 

e 3. Set the global pointer DTGPOINT [group] [ability] to the address of 
the allocated block of memory. 

e 4. Set the global variable DTGNUMBR[group] [ability] to the number 
of ability occurences counted, representing the number of 
occurences in the allocated memory block. 

e 5. Initialize this block of memory with the defintion from the script. 


Once the parse is complete the following defines Its result: 


e An ADAM has been created containing the ability definition 
encountered by the parse. 

e The ADAM's global variables DTGPOINT[group] [ability] has been set 
to the base address of the ADAM 


e DIGNUMBR{[group] [ability] has been set to the number of ability 
occurences in the ADAM. 


NOTE: The keyboard definition can viewed as an ability. The "termcap" file can 
be considered a d-tree script specific to the keyboard ability. The DT KEYBD 
function is the parsing function specific to the keyboard ability. The result of call- 
ing DT _KEYBD is an ADAM of type DTIKKEYBD. 
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The following outlines the flow of the DT COMPL function: 
1. Loop through all ability reference numbers of the current group. 
2. Check the global variable DTGNUMBR[group] [ability] for a value. 


3. If a value exists it writes the ADAM to disk in C source form. 
If no value exists it skips it. 


Because of the numerous types of terminals within the UNIX environment, you 
may wish to have the keyboard definition parsed at run-time for terminal inde- 
pendence while the remaining definitions can be hard coded into the C source 
code. This requires restricting the function DT COMPL from generating the C 
source code for the keyboard. This is done by simply setting its ADAM’s global 
number of elements to 0. 


DTGNUMBR[DTGCURGP][DTKKEYBD] =0 


The two global variables, DTGPOINT[group] [ability], a double subscripted array 
of pointers, and DTGNUMBR{group] [ability], a double subscripted array of in- 
tegers, both reside in the header file DT_ GLOBL.H. The variable 

DTGPOINT [group] [ability] contains the base address to the ADAM while the 
value of DTGNUMBER{[goup] [ability] is the number of occurences of a particular 
function within a particular group. 


The first subscript, [group], contains the group number. This is controlled by the 
global variable DTGCURGP (d-tree global current group). 

d-tree initializes this value to 0 and does not alter this value unless the GROUP 
ability is encountered within a d-tree script or is changed by a user program. 
The group facility allows for more than one ADAM of the same type to reside in 
memory at one time. Manipulating the group number determines which group 
(of ADAMs) is currently being used. Reference the GROUP ability in the 
Reference Manual for specific information concerning how to use the GROUP 
ability in a d-tree script. 


The second subscript, [ability], references the type of ability within the particular 
block of memory. Within the header file DT_DEFIN.H is a list of #define state- 
ments equating every possible ability with an identifier. 


Back to the keyboard. By setting its global number of elements to 0 we ’trick’ 
the DT_COMPL function into thinking that there are no ADAM for this keyboard, 
thereby circumventing the generation of the hard coded definition. We will use 
the DT_KEYBD function as in example one to interpret the keyboard definiton at 
runtime. 
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At this time insert the statement 
DTGNUMBR[DTGCURGP][DTKKEYBD] =0 


into the “ex _image.c" source file just before the call to the DT_COMPL function. 
Compile and run the "ex_image.c" program. Then, view the "ex_image.h" header 
file once again and note that the keyboard ability definition was not generated 
as when we first created it. All other ability definitions are created. 


ex_image.c 
break; 


case DTKBPD: printf ("page down was hit"): 
break: 

default: 
break: 

+ 7* end switch */ 


/“™ now lets check sone data to see if the input worked */ 


printf£( Number=4d", number); 
Insert statement here. 


printf£("Name= ~Zs,Name):; 


DTGNUMBRCE DTGCURGPIJCDTKKEYBDI]=8; <——————_- 


if (DT_COMPL( “*ex_image.h")) 
printf£C "Could not Urite Compile specs\n"): 


DT_SETTY(@): 


exit¢G@): 
> 


Print or view the file “ex_imag3.c". Compile this program. This example shows 
the interpreted mode illustrated in out first example together with the hard 
coded mode illustrated in example two, controlled with the help of #defined. We 
basically combined both techniques into one. This technique is also used in the 
source file "dt_score.c" which is the d-tree general mainline used for most stand- 
ard maintenance programs. 
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4.4 c-tree INTERFACE 


Experienced c-tree developers realize that there are a number of details involved 
in building and maintaining all the information and parameters required by the 
the c-tree file handling routines. Below are a number of the issues which must 
be addressed: 
e Parameter Files 
e Incremental Structures 
e Record Lengths 
e Field Offsets for Indexes (Hardware Word Alignment Considerations) 
e Record Buffers or 'C’ Structures 
e Special Data Handling (Packing and Unpacking Variable Length 
Records) 
e Target Value Construction (forming targets for keys). 
e Insuring ‘Clean’ Data (Proper Initialization and Padding) 
e Record Locking 
e Multi-User Interface (Simultaneous Update of Single Record by Multiple 
Users) 
e Data Portability in varying hardware environments 
e Opening, Processing and Closing Data Files 


d-tree provides a variety of ways to address these Issues. d-tree takes a unique 
approach in simplifying the task of building the requirements necessary to effi- 
clently use c-tree for database management. The following are a few of the fea- 
tures In d-tree to accomplish these tasks. 


e CATALOG (dtcatlog) - Capabilites built into the catalog program 
greatly simplify the following: 

Creation of Parameter Files 
Creation of Incremental Files 
Creation of Record Structures 
Record Length & Field offsets: where issues such as 
hardware alignments are considered in providing the database 
record lengths and field offsets for key segments. 


e DODA (Data Object Definition Array) - In order to support a script 
interface in d-tree, a table must exist in memory which contains the 
field symbolic names (used in the script), field addresses, field types 
and field lengths. This table is known as a DODA. The CATALOG will 
also generate DODA entries upon request. 


e Record Buffers - All c-tree calls that ‘get’ or retrieve data from disk 
require an address in memory to place the data. This address is the 
base address of what is termed a ‘record buffer’. 
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d-tree supports two methods of record buffer definition: 


e 1) Traditional - The typical manner that records are used in the C 
programming language is to build a structure which defines the data 
record. The address of the structure is what is provided to the c-tree 
‘get’ call. The record is then read into this structure. This method 
requires hard coding record structures into the source file which must 
be recompiled if the record definition changes. Using this method, the 
LODA will have the address of each field hard coded into it. The 
following diagram illustrates this method. NOTE: The catalog provides 
an easy way of generating C structures as well as DODAs, if the 
traditional method is used. 


TEXT name(3@); 
TEXT address(3@]; 
Jucol3]; 


DATOBJ DTSDDODAC] = { , 
C"’name™, uco. name, RTSTRING, 30}, Hard Coded| 
Caddress",uco. address, RTRSTRING, 30}, : — : 
a3 


e 2) Dynamic - d-tree can maintain data base records without the need 
to define the record buffer as a hard coded memory allocation (no C 
structures are necessary). This is done by supplying a NULL address 
for the fields in the DODA. This is illustrated in the following diagram. 


DATOBS DTSDDODA = 
C"name”,NULL,RTSTRING, 30}, 

| €address",NULL,RTSTRING, 30}, 

Bz 


Seer ~- address| 


DT_ALIGN function - Regardless of the method used to define the record buf- 
fers, DT_ALIGN must be called at the beginning of your program for initializa- 
tion. This call should follow two other calls. A call must be made to the following 
functions first: 
e DT_SETTY - A call to this function is mandatory in every program and 
will initialize d-tree pointers. 
e Open Data Files Cail - There are three different methods of opening 
the data files. 
- - Parameter file method - OPNISAM (c-tree) 
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- - Incremental file open - Combination INITISAM with OPNIFILS 
(c-tree) 
- - DT_IFILS - Handles all requirements for opening a file. (d- tree) 


Once the data files are open, d-tree has established the first and last fields in the 
DODA for each file. (See first and last parameters in Parameter Files or In- 
cremental Structures.) The DT_ALIGN function will perform the following tasks 
based upon the record buffering method used. 

e Using the Traditional record buffering method, the (hard coded C 
structures) the DT ALIGN function will verify the address set in the 
DODA. 

e Using the Dynamic record buffering method, the DT_ALIGN function 
detects the NULL address entry in the DODA, dynamically allocates an 
array of three record buffers for each file then appropriately sets all the 
field addresses in the DODA. (See Three Buffer Approach below.) 


Three Buffer Approach - Multi-user Conflict Checking - As noted earlier the 
Dynamic method of allocating record buffers automatically creates an array of 
three record buffers. When record buffers are defined as C structures (the Tradi- 
tional method) you MUST define an array of records. Three are required as 
illustrated. 


TEXT name(l30); 


TEXT address( 30]; 
yuco(3I: ———|]} Record Buffer Array 


d-tree utilizes this three record buffer approach to prevent multi-user conflicts. A 
multi-user conflict would be a situation involving two users attempting to write 
the same record at the same time. In a typical file maintenance application the 
following activity involving the three buffers will occur: 


e First the record is accessed by a c-tree ‘get’ call and read into the 
provided record buffer. For our example we will use record buffer #1. 
The record, once read into buffer #1, is immediately copied to buffer 
#2. 

@ 

e Actual modification to the record is performed in buffer #2. 

When the user commits this to disk, d-tree first acquires a lock upon 
the record. If a lock cannot be obtained this process fails because 
another user has the record. 
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@ Once a lock has been acquired, it rereads the original record back into 
buffer #3 and compares its contents against buffer #1. If no changes 
were made to this record by another user since the time you originally 
read the record, buffer #1 and #3 should be identical. If they are 
different, this is an indication that another user has modified this record 
and therefore it should not be written to disk, overlaying the other 
users changes. An error message should be presented to the user 
stating ‘An update cannot be made at this time. Another user has 
already made updates to this record. Please start your update process 
again.’ The programmer can control the message and the next action. 
If the comparison is successful, record buffer #2 is written to disk and 
the record lock is released. 


In review, this is a step-by-step explanation of how the three buffer method 
handles multi-user conflicts. 


e Read record from disk into buffer #1 

e Copy to buffer #2 

e Make changes to buffer #2 

e@ Lock record or Abort process 

e Read record from disk into buffer #3 

e Compare buffer #3 to buffer #1 

e Write buffer #2 to disk or Send Error Message 
e Release record lock 


Record Lengths and Index Considerations 
There are two methods, supported by d-tree, to define record lengths and its 
index: 

e Traditional - The Traditional c-tree methods are Parameter files and 
Incremental Structures. The Parameter File method stores the file 
definition and related information in a separate file identified by a ’.p’ 
extension. The Incremental File method hard codes the same 
information within your program. (Reference the c-tree manual for 
more detailed information on these methods of file defintion.) 


However, one problem that still exists for any data file is data 
portability. For instance, moving data from a 16 bit processor to a 32 
bit processor, the first being word aligned while the latter is double 
word aligned. The record lengths as well as offsets within a structure 
where fields reside can be different. This problem, experienced when 
using Traditional methods, can be tedious to the developer who works 
in numerous environments. d-tree provides a Dynamic solution to this 
problem. 
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e Dynamic - d-tree provides a means that you can define a method by 
which data and index file definitions files may be portable to and from 
differing hardware environments. This is accomplished by not hard 
coding record lengths, key lengths and key offsets within your 
incremental structures, since these are the factors which change from 
environment to environment. By applying special parameter entries to 
IFIL, IDX and ISEG definitions, d-tree can provide a portable means of 
defining your data files. 


e IFIL - d-tree will calculate the record length under the following 
conditions: Enter a record length of zero (0) (fixed length file) or the 
DODA occurrence number of the first variable length field in the record 
(varaiable length file). In order to recognize the records as being 
variable length, d-tree references the file mode entry. If the file mode is 
less than 0, it is assumed that this is a variable length file definition and 
the value found in the record length is the occurence number within 
the DODA of the first variable length field. The negative number 
assigned in the file mode Is the valid file mode simply prefixed by a 
minus ("'-") sign. (le. file mode = 5 variable length file mode = -5) 
d-tree will convert this entry to the proper positive representation. 
d-tree will then determine the record lengths. (the DODA ocurrence 
number aids In setting the fixed length portion of a variable length file). 


e IIDX - Index Structures - The key length is the entry which must remain 
flexible within the IIDX structure. Instead of hard coding the key length 
enter a -1 to prompt d-tree to calculate the key length. 


e ISEG - Key Segment Structure - The segment offsets are the eniries 
which must remain flexible. Enter the DODA occurence for the field to 
be used prefixed with a minus sign ('-"). The negative value indicates to 
d-tree that this is a DODA occurence and not the actual key segment 
offset entry. d- tree will strip the minus sign and use that value at 
run-time to determine the proper physical offset value. NOTE: See 
DTCATLOG.H for a good example of how these techniques are used in 
the CATALOG program. 
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c-tree Interface Related Functions 
d-tree provides a number of functions to greatly simplify interfacing with c-tree. 


DT_IFILS - Opening all the files required in a program. DT_IFILS performs the 
following tasks: 

e If an IFILS ability section has been defined in a d- tree script file, 
DT _IFILS is used to access the data dictionary and load into memory 
all the required data file and index file definitions. 

e Performs all initialization required for c-tree, counting the required files 
and performing an INTISAM call. 

e Sets any defined portability requirements. (As discussed in Record 
Lengths and Index Considerations of this chapter.) 

e Opens all defined incremental files. 

e Optionally rebuilds corrupted files. #define DTRBLIFIL must be must in 
the header file DT DEFIN.H. 


DT_ADREC - (Add a record to a c-tree file) - d-tree will perform the following 
tasks in an add condition: 
e Pads the records 
e Performs any UNIFORMAT logic required 
e Determines if records are fixed or variable length 
@ If variable length, Packs the record 
e Acquires a new record position and locks it 
@ Adds the record 
e Frees the new record lock 


DT_DLREC - (Delete a record) - d-tree will perform the following tasks in a 
delete condition: 
e Determines if records are fixed or variable length 
e Performs appropriate c-tree delete call 


DT RWREC 
- (Rewrite a record) - The rewrite operations of d- tree 
automatically performs the following tasks: 

e Performs multi-user interface conflict checking 
e Pads the records 
e Performs any UNIFORMAT logic required 
e Determines if records are fixed or variable length 
e If variable length, Packs the record.) 
e Performs call to record lock 
e Rewrites the record 
e Frees the record lock 
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Data Base "GETS'"- 


DT FSREC Get the first record in a c-tree file. 

DT _NXREC Get the next record in a c-tree file. 

DT _PVREC Get the previous record in a c-tree file. 

DT_EQREC Get a data record with a key value equal to the target value. 


The read logic performs the following tasks: 
e Determine if fixed or variable length 
e Access the record 
e Unpack variable length records © 
e Performs any UNIFORMAT logic required 
e Unpads the record 


Miscellaneous Data Management Functions 


DT EDRRD Re-read record; Main function for multi-user conflicts. 
DT DOINT Initialize d-tree record buffers. 

DT _UNPAK Unpack records. 

DT DOPAD Pad fixed length fields. 

DT UNPAF Unpad record structures. 

DT VLOUT Pack a variable length before writing to disk. 

DT VLINN Unpack a variable length record after reading from disk. 
DT AVREC Add variable length records. 

UNIFRMAT Uniformat 
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Other d-tree Features 


5.1 Print Screens in Xenix/Unix Environment. 


d-tree allows a "print screen" capability in environments where a "print screen" is 
not typically supported. By setting the #define DT_PRTSCR in file dt_defin.h, 
this feature is activated. d-tree is shipped with this #define already set. When 
the user hits the "print screen" key as defined in the TERMCAP file, the image 
out function (DT_IMGOT) is called to redisplay the screen. Note: The output 
functions in d-tree are passed file pointers to where the output is to be directed. 
Normally DT_IMGOT is called with stdout as the file pointer. When the “print 
screen" is hit a temporary file is created (using the your runtime lib’s tmpnam 
function call). The DT_IMGOT is called with this file pointer "dumping" this 
screen into this file. The code in “dt_image.c" shown below then prints the file. 


dt_image.c 
sifdef DOS 
strcpy(prtque, ‘type °); 
strcat( prtque, prtfile); 


strcat(prtque,” > °'); When the “print screen” key is 

strcat( prtque,geteanvu( ’PRINTER™)): hit. d-tree writes the screen 

systen( prtque):;: to a temorary vork file which 
telse is printed via this code in 


strcpy(prtque, "lp -d‘’); file “dt_image.c”. 
strcat( prtque, getenvu(*’PRINTER™)); 
etrcat(Cprtque,” -s -ce “); 
strcat(prtque, prtfile): 
system( prtque);: 

Bsendif 

+ 


With a little creativity, the DT_IMGOT function can be used to create simply 
reports, where the output is "painted" as an IMAGE in a d-tree script, and the 
DT_IMGOT function does the output to the given print file. 
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9.2 Direct memory video writing/Color Support. (DOS ONLY) 


Writing directly to the video memory in order to provide INSTANT screens is 
controlled by the #define INSTANT in the file dt_defin.h. The logic that actually 
performs this task is written in assembler and can be found in the directory 
\INSTANT on the last distribution disk. These modules have been compiled 
and placed in the library called DTDOSL.LIB in the \INSTANT directory. 
Program compiled with #define INSTANT must be linked with this library. At this 
point in time, all color support is done thru direct video memory access, ther- 
fore the #define INSTANT must be set for color. Color support also requires a 
TERMCAP terminal entry that defines the colors. The supplied terminal definition 
named DOSCOLOR will suite DOS users. We have not used d-tree to control 
color on ANSI type terminals (wyse, televideo, etc). If these colors can be con- 
trolled with esccape sequences, the sequences define in the TERMCAP file 
should be able to handle it. 
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6.0 TERMCAP - Terminal/Keyboard Interface 


The TERMCAP file is a text file containing definitions of screen and keyboard 
configuration. These definitions will be used at run time to define the current 
terminal's characteristics. The format of these definitions has been designed to 
be straight forward, relating a simple identifier to a decimal sequence(s). These 
identifiers can be broken down into two different categories, values returned by 
the keyboard and escape sequences sent to the terminal device. For example, 
‘CR’, Carriage Return, is equated to the decimal representation returned by the 
keyboard, 13, ‘BU’, Back Up, is equated to a decimal value of 8, and so on. 
Closer to the bottom of the file you will see the screen attribute symbols and the 
string of ESC sequences necessary to produce the attribute. A complete table 
of delivered symbols may be found in the file dt_keybd.h. 
, TERMCAP 

TERMINALC DOS) 
ESC 27 27 CR 13 BU 8 DC @ 83 IC @ 82 DU @ 8B UP @ 72 PD @ Bi PU @ 73 
LF @ 7S RT @ 77 HM @ 71 EN @ 79 AD JB 
Fl 8 S53 F2 @ 68 F3 @ 61 F4 @ GZ FS BB 63 F6 B G4 F7 @ GS FS B@ 66 FI B G7 Fie @ 
Fii 3 CTLA 1 HELP S36 


LOC @ 27 391 128 S93 121 72 CLS 27 91 S@ 74 EOL 27 391 75 
UL 2? 931 SZ 189 RI 27 91 SS 189 NA 27 SL 48 189 PS 2 HL 27 G1 


LOTUS 27 31 5S 189 
The keyyvord TERMINAL is required. | 


FRAME_LTC 201 
The Terminal Name must immediately Follow 
the TERMINAL keyword in parenthesis. 
TERMINALC uyseS@) 


FRAME_RTC 187 
FRAME_RBC 188 
FRAME_HOR 2@5 
FRAME_VIR 186 


FRAME_LBC 288 

ESC 27 27 CR 13 BU 8 DC 127 IC 27 88 DU 10 UP 11 PD 27 74 PU 27 75 

LF 8 RT 1Z HM 38 EN 27 SS AD 9 Fl 27 49 F2 27 SB FS 27 51 F4 27 SZ FS 27 SB 
FG 27 S4 F7 27 123 FG 27 SG FS 27 S7 F18 27 58 CTLA 1 

Fi1 3 


The only deviation from the screen attributes found in the TERMCAP file occurs 
when direct video writes are used. 

NOTE: Although d-tree is delivered with some example terminal definitions, it is 
the user's responsibility to construct his own entries. It will be necessary for you 
to refer to your terminal documentation to obtain the information necessary to 
create a complete terminal defintion. Although DOS terminal definitions are fairly 
standard and the default terminal definition will work quite adequately for your 
needs, there may be some keystrokes you will want to redefine to meet your 
preferences. ie HELP key, POST key, DEFAULT key, etc. The necessity to 
create a new terminal definition mainly applies to non-DOS environments. 
DTERMCAP-The utility program dtermcap is provided to simplify the insertion 
of new terminal definition scripts in the TERMCAP file. To insert a new terminal 
definition in the TERMCAP file start the utility program by entering: dtermcap 
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d-tree will first present an instruction screen defining the valid keystrokes during 
data entry. These are: 

KEY DESCRIPTION 

. Backup one keystroke definition. 

‘+' Accept this entry and proceed to the next prompt. 

‘|’ Abort the definition entry operation. 

The first data you must enter is a Terminal Name. This name will be used to 
identify the terminal definition in the TERMCAP file. 


C:\DT *dtermcap 


FairCom Termcap Setup 
d-tree (tm) 
Copyright (c) 1988 


This program will prompt you for a series of keyboard strokes. 

As a key is hit, it’s decimal representation is echoed to the screen. 
Once you have defined the keystroke(s) for a purpose. (Page Up....ect) 
press the °+’ key to advance to the next definition. The °-’ 

key is used to back up if you make a mistake. The ’|’ key is 


used @ an ABORT key. 


Siew. Taree nel NE. 5 a ks 5% x Oe 40d do Kk how Se wee 


dtermcap then proceeds through the keystroke definitions entry by entry prompt- 
ing you to press the equivalent keystroke on your keyboard. 


nter Terminal Name 
nter Escape Key... 
Terminal Name 
Backup Key 
Delete Character... : 
the terminal ID Post Key 
used in the This key is used by 
-|[TERMCAP file. the CATALOG program 
to write input to 
disk. Typically 
the END key is 
defined for this 
purpose, 


rint Screen Key Coptional-skip in DOS) Default Control Key 
elp Key This key is used to 
Help Key ‘ insert a default 
In this example value into a data 


oe ee 

KE ic eb e's ots Gs 
key is defined for 
this purpose. 
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After completing all the keyboard definitions dtermcap will then begin prompting 
you for screen attribute definitions. It will probably be necessary for you to have 
the documentation for the terminal being defined at hand for reference. 


Shift + Fkey if 
your keyboard only 
goes to F1@. 


sequence 
an x for row and y for column)...128 121 
tlear Screen Sequence 
clear to End screen I/0. Refer 
ormal or No to your terninal 
documentation for 
the proper entries. 


alf Line Feed sequence (optional) 
eranet Left Top Corner 


Once all the terminal characteristics have been defined, dtermcap will ask if you 
wish to test the terminal definition. A ’Y’ will test the definition while 'N’ will ter- 
minate the terminal definition installation session. 


Advanced TERMCAP Concepts 
The remainder of this section will be given to more detailed information concern- 
ing the mechanics of the terminal definitions. Topics such as: 
e How these definitions are actually used by d-tree. 
e@ How to add a new terminal characteristic to the TERMCAP file as well 
as all other necessary files. 
e How to include the new terminal characteristic in the dtermcap utility 
program. 
Terminal definitions are treated by d-tree as simply a d-tree script. At run time 
these terminal definition scripts are parsed by the function DT KEYBD and 
stored in a typedef. When calling DT KEYBD you must pass it two parameters, 
the TERMCAP file name and the terminal identifier to be parsed. DT_KEYBD will 
parse the definition script, allocate a block of memory and load the parsed 
definition into that memory forming an Ability Definition Allocated Memory block 
(ADAM) of type DTTKEYBD. 
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At typ h, fy ememeenencnnenneneeensienescensestssasennineteaness 


PA Liisi titi tt ttt ee tet ttt i trettrtetttettt tite tit-tttttt tite rit tii t tt tA 
“* KEYBD definitions 7 

wifdef DTKKEYBD 

typedef struct { 


COUNT terminal: 7* terminal id */ 

COUNT retcode; 7% what to return if input matches*/ 
COUNT frschar; 7* first char of key sequence */ 

COUNT noofchar:;: 7* no of additional char in sequencex/ 


TEXT addchar({DT_MXSEQ]; /»* additional chacters in seqence */ 
+ DTTKEYBD: 


EXTERN COUNT DTKEYMAPE256]: 7 keyboard map array “/ 


7x note-do not assign (-1) to any screen seq or keyboard key */ 

7m for (-1) is used to detect termination 7 

“7* remember that all screen sequence numbers must be numbered */ 

7* sequentually without skipping any numbers betuveen the first */ 

7* and last number / 

7» there are two types of output attributes for a field */ 

“* screen control seq is one type, and simple output attributes that */ 
7*% do not involve special screen seq is another */ 


Adding A New Keystroke or Screen Attribute Definition 

Let's add both a new keystroke definition and a new screen attribute to our ter- 
minal definition that is not currently defined in d-tree. In our keyboard definition 
we will insert a "HOT KEY’ definition and in our screen definition we will add the 
‘BLINK’ attribute. 

First we must edit the header file DT_TYPDF.H. Postion yourself at the bottom 
of this file. Notice that the #define statements for all the screen attributes begin 
with the prefix DTSC, d-tree Screen Control. e.g. DISCCLS = d-tree Screen 
Control CLear Screen. Above these entries are the #define statements for all the 
keystroke definitions beginning with the prefix DTKB, d-tree KeyBoard. 

Within this header file, DT_TYPDF.H, we must enter a new #define statement for 
each additional definition we wish to insert. We will first add the BLINK’ screen 
attribute. Notice the two #define statements: 

#define DTSCFRST (-10) 


#define DTSCLAST (-23) 


NOTE: If the value in parentheses on the second line is not (-23), substitute the 
correct value whenever the value of DTSCLAST is referenced in this session. 


6-4 d-tree Reference Guide 


tdefine 
tdefine 


DTSCFRS 
DTSCLST 


{(~16@) 
c=—24) 
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oe “tupd?. 
“* define first screen sequence number */ 


mp last 
rae! 
7 The DTSCLST, d-tree 


screen sequence number */ 


tdefine DTSCLOC (-10) */ 
ttdefine DTSCCLS (~i1} ) */ 
tdefine DTSCEOL (-12) /“™ scrij/Screen Control Last, 4/7 
tdefine DTSCNON (-13) /7* noniivariable must be “7 
tdefine DTSCUL (-14) /4™ scrijadjusted. / 
tdefine DTSCRI (-15) “* reve seme ss 7 
tdefine DTSCHL (-16) /“™* half line feed */ 

ttdefine DTSCLOTUS (-17) /7™* lotus style */ 

tdefine DTSCFMLTC (-18) /7* frame left top corner character */ 
tdefine DTSCFMLBC (-19) /“™ frame left bottom corner character *7 
tdefine DTSCFMRTC (-28) “* frame right top corner character */ 
tdefine DTSCFMRBC (-21) /“* frame right bottom corner character */ 
udefine DTSCFMHOR (-22) “* frame hoizontal line character */ 
tdefine DTSCFMUIR (-23) 7™* frame vertical line character */ 
tdefine DTSCBLINK (-24) 7™ screen blink */Z 

| tft is our new screen entry. 
tdefine DTKBESC (-3@) 

ndefine DTKBCR 


(-31) 7 Cr-Return on keyboard 


—— 


— 


These entries, d-tree Screen Control First and 

d-tree Screen Control Last 
define the boundaries of the screen control sequence numbers. All screen con- 
trol sequence numbers must be within the boundaries established by these two 
#define statements and they must be In sequential order. 
To add a new screen control attribute the DTSCLAST value must be adjusted to 
make room. Edit this statement to read: 
#define DTSCLAST (-24) 


(or add -1 to the negative value of your DTSCLAST) 
Insert the statement: 
#define DISCBLINK (-24) /* screen blinking attribute */ 


immediately following the last DTSC #define statement. 

Next we must insert our new keystroke definition. View the keyboard related 
#defines. Note that each of them begin with the prefix DTKB. These entries are 
not restricted by any sequence number boundaries. The only requirements 
placed on keyboard entries are that the sequence number may not be dupli- 
cated, the real value of the sequence number must be greater than that of the 
real value of the greatest screen control sequence number and all entries must 
be in sequential order. 

Insert the following statement immediately after the last DTKB #define statement 
incrementing the sequence number: 

#define DTKBHOT (-67) /* Hot Key sa 


(The value in parentheses may be different from what you may need to enter.) 
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= ausneeeEEE dt_typdf. i eee 
tdefine DTKBFG (-S@) 7% function key F6 */ 
tdefine DTKBF7 (-S1) /* function key F7 7 
tdefine DTKBFS (-5Z) 7* function key F8 */ 
tdefine DTKBFS (€-53) 7%* function key FSI / 
tdefine DTKBF1@ ¢(-S4) /* function key F1@ 4 / 
tdefine DTKBF11 ¢-S5) /* function key Fil */ 
tdefine DTKBF12 (-56) 7% function key F12 / 
tdefine DTKBF13 (-S7) /* function key F13 aS 
#define DTKBF14 (¢-58) /* function key F14 */ 
tdefine DTKBF1S (¢(-S9) 7% function key F1S “7 
tdefine DTKBF16 ¢-68) 7 function key F1i6 */ 
wdefine DTKBF17? ¢-61) 7* function key F17 “eS 
wdefine DTKBF18 (-62) /* function key F18 */ 
tdefine DTKBF19 (¢(-63) /“* function key F139 / 
tdefine DTKBFZ@ (-64) /%* function key F2@ / 
udefine DTKBCTLA (-65) 7* control 1 / 
tdefine DTKBHELP (-66) 7% HELP key “7 
wdefine DTKBHOT ¢(-67) 7% HOT KEY */ 


This is our new keyboard entry. 


endif pareats 


L, YE IEEE DE DEDEDE DEDEDE DEE DE DE HE DE DE DEDEDE IE 


d€ dE DE dE DE DE DEDEDE EEE HK 


Save all edits made and exit from editing the DT TYPDF.H header file. 

We must now add our symbol names within the header file DT KEYBD.H. Within 
this file is the table that is used to assign the symbol reference that will be used 
in the TERMCAP file. For clarity in organization only, the keystroke symbols are 
first, followed by the screen control symbols. Let's insert our new symbols be- 
tween these two sections. Immediately following the last DTKB entry, insert 
these two entries: 


{"HOT" ,DTKBHOT}, —/*Hot Key fi 
{"BLINK",DTSCBLINK}, /*Blink wd | 
: : dt_keybd.h a aoe = 
C(°F6" ,DTKBF6}, 7* function key F6 / 
C°F7" , DTKBF7}, 7* Function key F7 «7 
CFS" ,DTKBFS}, 7“ function key F8 a7 
C’FS" ,DTKBFS}, 7* function key FSI a7 
C°F10" ,DTKBF1@}, /* function key F1@ "7 
C{°F11" ,DTKBF11}, “7* function key Fil 7 
C°F12" ,DTKBF12}, 7* function key F12 7 
C°F13" ,DTKBF13}, 7* function key F13 af 
€°F14" ,DTKBF14}, 7* function key F14 a7 
C°F1S" ,DTKBF15S}, 7* function key F1S 7 
(°F16" ,DTKBF16}, 7* function key F16 ad 
C°F17° ,DTKBF17}, 7* function key F17 a 
{"F18" ,DTKBF18}, 7% function key F1i8 These tuo lines contain 
C°F19" ,DTKBF19}, 7* function key F139 & tuo new entries. | 
C{°F28" ,DTKBF2Q}, 7* function key F2@ SE 


*/ 


C°HELP’’, DTIKBHELP?}, 7* help key 

{"CTLA”’,DTKBCTLA}, /7* control A / 
C**HOT’ , DTKBHOT}, 7* hot key 7 
C° BLINK’, DTSCBLINK, “* screen blink 7 
C°LOC’ ,DTSCLOC}, 7* screen locate mS 
-"tis . DPSCCLS), “7* screen clear screen 7 


{°EOL” ,DTSCEOL}, 7* screen clear to the end of line / 
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We have completed all the necessary steps to make a new keystroke definition 
and screen ability definition recognizable by the DT _KEYBD parsing function. 
Therefore, their associated new symbols may now be used in the TERMCAP file. 


INSERTING THE DTERMCAP PROMPT 


The next step is to include our new keystroke and screen attribute in the 
TERMCAP installation program, dtermcap. This requires us to edit the header 
file DTERMCAP.H. Within this file are all the prompts which are used by the 


dtermcap program. 


The order that these prompts appear is the same order the prompts will be 
printed on the screen. Insert the prompts for both of our new features in 


whatever order you would like to have them displayed. 


The final step to making the insertion of our new features complete is to compile 


the following modules: 
DT _INPUT.C 
DTERMCAP.C 


REVIEW 


In review, the addition of a new feature to the TERMCAP file requires the follow- 


ing steps: 


e Edit the DT _TYPDF.H header file inserting the appropriate #define 
statement. If the type of feature being inserted has a last sequence 


number variable these must be adjusted by -1. 


e Insert the new symbol name in the header file DT KEYBD.H. 
e Insert prompts for the new symbols into the header file DTERMCAP.H 


to be used in the dtermcap installation program. 
e Compile DT_INPUT.C and DTERMCAP.C 
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a dtermcap.h 
Fis Nea en ee er eR a ee ae ee ee a a ee ee a ee . DTKBF15}, 
OMG Re ear car ann & ements Dia rh ee ep eames Strneeuita *, DTKBF16}, 
Oe ee oT oak Was ws a a ee ak ACerS oe eee * DTKBF17}, 
BE ats MRL re aA eae ye ao pete a AEE tee Re a ts * DTKBF18}, 
DPA Wes hcg ee a as ew Sc a Re a * DTKBF19}, 
Tee Es bon ha eee Ce oe ee ae ee wee Weare eee “  DTKBF2G}, 
"“CORTTOL Fae PROLIGHAL Dc i acdec wees eas ebe eens * DTKBCTLA}, 
SOD SR a EWS Ae eg ee he he ee ORS OR ee **, DTKBHOT}, 
OM teas sek oo ese eR Oo ERE ROSNER eG **, DTSCBLINK}, 
Testiton Cerecr OW SEFAON: 6506555005 cuca eeseabn ~, DISCLEC}, 
2S SEVHOR SOGNGACe. oaks cio eee ke vo ws KS ” DTSCOCUSS ; 
EhOae £0 End OF LANG ois ces cence iow eee ee neues * DTSCEOL}.|jtvo entries for 
NOPMAL Gr TS BECO bee: oak coins teen eter eee es **, DTSCNON}, 
Sndariing Seauinees.6 S46 veh ia ce od Sls od awe oo ee  DTSCULD. 
‘Reverse Jeahe SOGUMNEE 66 4 65 55.06 ooo a5 wasn eee s  o OTe) 
AER UL OS BEESON Ce. ce ew wk oe eee  , DTSCLOTUS}., 
"Half Line Feed sequence (optional).........000. “DTS , 
Pree) SHEL: Tap CORnG rs 665 sks Saw eee we eee **, DTSCFMLTC}, 
"FYEMO! THREE BOLtae Corner sc. 50 65 ok oe ee as ees *, DTSCFMLBC}, 
part Right ‘Tou C6rnetis sobs aie ekw ions eta ees * DTSCFMRTC}., 
-erenet Right Bottom Corner... <i «ik eee vevess vess * DTSCFMRBC}. 
re nee: AS BOCES Le 6 ooo Oe Oo we wee oe **, DTSCFMHOR}, 
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d-tree Ability Reference Guide. 


This section will described the abiliies defined in d-tree. 


d-tree ABILITY - The term ability can be used in many contexts. For clarity we 
will outline what constitutes a d-tree "Ability’. 


@ An "Ability" is an activity to be performed by a program for a particular 
purpose. (ie: screen I/O) 


e An "Ability" is given a reference name. (ie: IMAGE). 


e An "Ability" is assigned a reference number in DT_DEFIN.H. 
(ie: DTKIMAGE) 


@ An "Ability" definition typedef is defined In DT_TYPDF.H to contain the 
on definition of objects necessary to perform the ability. (le: DTTIMAGE) 


@ An "Ability" requires an initialized ADAM containing definitions of its 
related objects (see section 4 for ADAM definition) 


e@ An "Ability" has a d-tree script interface syntax definition. 
(ie: IMAGE(master) ) 


e@ An "Ability" has a parsing function which is used to convert its script 
definition into an ADAM. (ie: DTPIMAGE) 


e An "Ability’ has related function calls to perform its objectives which 
use a pointer to the ability’s ADAM for required definition. 
(ie: DT IMAGE, DT_IMGOT, DT_IMGIN). 


This focuses on each ability, providing specifics relating the the concept listed 
above. 


7.1 CALCS - Calulations 


7.1 CALCS - Calulations 


DESCRIPTION: 

The "CALCS" ability provides the capability to define calculation expressions 
from within a d-tree script. Typically the CALCS ability will be used in conjunc- 
tion with symbolic names from the DODA. 


SYNTAX: 


CALCS (reference name) 
symbol name operator symbol_name2 ... 


dtcatlog.dts 


CALCS( dup_sub) 
ikeylen — Cikeydup ™ 4) 


Proven] [ence] 


reference_name- The reference_name must be a unique Identifier for each 
CALCS definition. 


symbol_name- The symbol name must be a field defined within a DODA ora 
literal value. 


operator- The operator must be a valid mathematical operation. The 
supported symbols are: 

+ Add 

: Subtract 

= Multiply 

/ Divide 
(Note To Advanced Users: The evaluate function (DT EVALU.C) may be ex- 
panded to support additional operators.) 


RELATED FUNCTIONS: 
e DTPCALCS- Parsing function which initializes the DTTCALCS typedef. 
e DT_CALCS- Performs the calculation returning a result either in the | 
form of a long integer or double float. 
e DT _CALMP - Performs field mapping with a calculation. 
e DT _EVALU - Evaluates a postfix expression. 
e DT _PSTFX- Converts an expression in infix form to postfix. 
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TYPEDEF: 
DTTCALCS 


; ames dt typdf.h 

A, PE DEDEDE DE DE DE DE DE DE HE DS DE DE DE DE DE DE HE DE DE DE HE DE HL Da DE HE dD DE DE DE DE DA Dk De Dak DE DED ek DE Dk Dk Da DE Dk Ak Dk Dk PE PE DE Dk Pk ED De EE DE DEE EEE 
7* CALCS definitions */ 

xifdef DTKCALCS 

typedef struct { 

COUNT num: 7* calculation number */ 
TEXT *string: 7* calculation string */ 

+ DTTCALCS: 


tendif 


7, P44 D4 DE DE DE DE DE DE DE DE OE DE DE DE DE DE DE DE DE DE DE DE DA DE Dek DE DE Dk Dk DE DE DE DE DA Dk DE DE DE DE DE DA Dek Dk Dk ED Dk ED Dk Dd DE Dk ak DE ek EE Ee EEE 


EXAMPLE: 
An interest calculation may appear within a d-tree script as follows: 


CALCS(int_calc) 


(custbal * int_rate)/12 


The following source file example illustrates how the calculation in the d-tree 
script may be referenced: 


yfunction() 


ONG iresult; 

DOUBLE dresult; 
OUNT calcno; 

alcno = DT_INAME(‘int_calc"); 
T_CALCS(calcno, &iresult, &dresult); 


{(iresult) 

print{("The answer is %ld",iresult); 
Ise 

print{("The answer is %lf",dresult); 
eturn(0); 
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7.2 CONST - Constants 


DESCRIPTION: 

The "CONST" ability provides the means to define output attributes for constant 
fields within an image. A ‘constant field’ is any character or group of characters 
found on the screen image which is not an input field. This includes field iden- 
tifiers, headers, titles, special system symbols (prefixed with an ’@’ sign) and 
frames (denoted by '+’ signs). One or more words that reside on the screen 
delimited by a single space are grouped together as one constant. Constant 
values are delimited by a white space or two or more blank spaces. 

"CONST" is used in conjuction with "IMAGE". The "reference_name" in paren- 
theses following the keyword "CONST" must be the same as that of the cor- 
responding "IMAGE". 

Constants are identified by an associated sequential numbering method. All con- 
stant values are counted in sequence beginning at the top left, progressing left — 
to right, top to bottom. (Special note: When determining the sequence number 
for constants, do not count FRAME TITLES.) Frame Attributes are assigned to 
the top left corner constant (top left + sign). 


SYNTAX: 
CONST(reference_name) 
value output_attribute 


CONST(C master) 
Z RI 


4 EOL UL RED 
S LMAG 


reference_name: The “reference name" must be identical to that of the cor- 
responding "IMAGE" section. 


value: The "value" is the coinciding sequential constant number. 


output_attribute: The "output_attribute" is the output attribute to be applied. The 
following is a list of available output attributes: 


Rl Reverse Image WHITE white 

UL Underline GREY grey 

Ek. Clear to End of Line LBLUE light blue 
before displaying constant LGREEN light green 

BLACK black CYAN cyan 

84 o blue PINK pink(light red) 

GREEN green LMAG light magenta 

CYAN cyan YELLOW _ yellow 

RED red BWHITE _ bright white 

MAG magenta BROWN _— brown 
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RELATED FUNCTIONS 


e DTPCONST - parsing function which initializes the DTTCONST typedef. 
e DT_CONST - Display a constant (constant out). 


TYPEDEF: 
DTTCONST 


dt_typdf.) ——= 


Ve ttt ttt ttt ete eet eee tt tet ett ett eet ett ttt ttt ttt tt ttt ttt tt-t-t-t-t-t-t-t-t-t- 94 


7* CONST definitions */7 
ifdef DTKCONST 

typedef struct { 

TEXT *string: 

COUNT len: 

COUNT outatr( DT_MXOATI: 


COUNT col; 
COUNT rou; 


pointer to constant text 
length displayed on screen 
output attributes 

column number for display 
row number for display 


+ DTTCONST: 


tendif 


Va tit eePe tt et ttt eee Et tee rete tere et itt tt ttt tt-t-t-t-t-t-t-t-t-1-t°t 4 


EXAMPLE: 


t3 —» @TINME 


@DATE #1 


as 8S 


+Customer Master 


RZ—> FairCom 


@®CWD <— #4 


86 Customer Number: 
#7? Customer Name: 

x8 Customer Status: 
#3 Customer Balance: 


21Q ————» + 
FIELD( master) 
7* Symbol Name 
custnum 
custnam 
custstatus 
custbalance 


Input Attribute 
NUMERIC 
ALLUORDCAPS 
ALLCAPS 
NUMERIC cae —_ 


The first constant vill 
CONST( master) | 
2 UL | 


be underlined. The next 
4 BLUE WHITE 


Output Attribute Input Order I/0 Mask» 


Will have a forgound of 
blue with background white 


INTERNAL d-tree REFERENCE - DTIKCONST 
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7.3 DEFAULTS - Default field values 


DESCRIPTION: 
The "DEFAULTS" ability provides various methods of initializing DODA fields with 
data. 


SYNTAX: 
DEFAULTS (reference name) 
symbol name type_option default_value 


DEFAULTS( master) 

“7* Symbol Name Type of defaults Defaults value */ 
custaddress DFALT_KEY Unknown 
custstatus INIT OPEN 


activedate INIT SYSDATE 
activetime INIT SYSTIME 
custzip DUP_DFALT 

custstate DUP_INIT 


reference_name- The "reference_name" must be a unique identifier for this 
DEFAULT definition section. 
symbol_name- The "symbol_name" must contain a Symbol Name defined in the 
| corresponding DODA. 
type_option - The "type_option" determines how the default entry will be 
accomplished. The following are valid "type option" entries: 


e DFALT_KEY - The default value will be placed In this field when the 
user presses the Default_Key as defined in TERMCAP. The Default_Key 
Is assigned to the TAB key in the provided TERMCAP. See TERMCAP 
section to assign a different key to be used as the Default_Key. 

INIT - The default value will be placed in the field upon a call to the 
function DT_DFINI(). The purpose of this function is to perform all 
initialization type defaults defined in a given DEFAULT definition 
section. For example- The following steps illustrate the use of the 
DT_DFINI function when adding a new record to a file: 

1. A record buffer is initialized - DT DOINTQ 

2. Record buffer is initialized with default data values - DT_DFINITQ 

3. Screen image is displayed 

(See the DT_DOINT and DT_DFINI function descriptions.) 

DUP_DFALT - The value of this field in the previous record will 
automatically be duplicated to the current record when the user 
presses the default key as defined in the TERMCAP file. 

DUP_INIT - The value of this field in the previous record will 
automatically be duplicated to the current record upon execution of the 
DT_DFINI() function, commonly at initial screen image presentation. 
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default_value - The "default_value" must contain the data used to initialize the 
corresponding field. The maximum character length is 
determined by the length of the destination field. This may be 
numeric data, a string of characters or one of d-tree’s special 
default values. These special default values are as follows: 


@ SYSDATE - If the entry "SYSDATE" is found, the system date will be 
placed in the corresponding field. 

@ SYSTIME - If the entry "SYSTIME" is found, the system time will be 
placed in the corresponding field. 


RELATED FUNCTIONS 
In this section we will discuss in more detail how the associated functions relate 
to the various types of defaulting methods. 


DT_DFINI 

We will begin with the most straight forward variation of the DEFAULT ability, 
the initialization (INIT) type of default. This form of default entry is performed by 
the function DT_DFINI. The parameter used by this function is a default number 
(dfaltno). The DT_DFINI function will initialize all fields in a specific default defini- 
tion section that are of types INIT or DUP_INIT. Let’s assume the following 
default ability definition for a d-tree script. 


DEFAULTS(sample1) 
symbol_name type_option default_value 
chkflag INIT 


errflag INIT 
Status INIT 
date DUP_INIT 


In general, most d-tree functions reference ability definitions with an associated 
ability reference number. A string of characters cannot be used directly in a 
function call. For the users convenience, d-tree scripts allow character strings to 
identify a particular ability definition section. The parsing routine will assigna 
reference number to each ability definition. To retrieve this reference number, 
call the function DT_INAME passing it the reference name used in the d-tree 
script. The following example illustrates how this may appear within your C 
source file. 


yfunction() 


OUNT dfaltno; 
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The final result of the DT_DFINI function call will be the initialization of the ad- 
dresses of the symbol_names to the values specified by the default_value for 
this definition section. The only stipulation placed upon entries into the sym- 
bol_name field is that they must be defined in a DODA. In this example we are 
concentrating on the initialization type of default, so we have used both the INIT 
and DUP_INIT keywords for the type_option. The default_value should con- 
tain the data to be used to initialize the address of the symbol_name. (Note: By 
using the DUP_INIT type, the contents of the date field will be duplicated from 
the previous record.) 


IMAGEC master) {LSTFLD_ADUANCE} {FRSFLD_BACKUP} 
@DATE = FairCom @TIME 


@SCUD 
+Customer Master 


Customer Number: 
Customer Name: 
Customer Address: 
Customer Status: 
Customer Balance: 
Active Date: 


SSE 


FIELD( master) 

“™ Symbol Name Input Attribute Output Attribute Input Order */ 
custnum NUMERIC RI 1 
custnan ALLUORDCAPS NONE Zz 
custaddress SCROLL NONE 
custstatus ALLCAPS NONE 4 
custbal PROTECT NONE = 
activedate NONE NONE 6 

DEFAULTS( master) 

“* Symbol Name Type of defaults Defaults value ™/Z 
custaddress DFALT_KEY Unknown 
custstatus INIT OPEN 


activedate INIT SYSDATE 


In this example when DT_DFINI is called in the program the customer status 
field will be set to "OPEN" and the "Active Date" will be Set to the system date. 
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DT_DFIMG - The next form of the INIT default type requires the use of the 
IMAGE and FIELD abilities. This variation of the INIT default uses the default 
image function, DT_DFIMG. This function is passed an image number. 
DT_DFIMG will first search for all fields associated with an image for which an 
initialization type default (i.e. INIT or DUP_INIT) has been defined. If any are 
found, they are executed. 
The following is an example source file: 
yfunction() 


OUNT imageno; 
mageno = DT_INAME("master’); 


DT_DFIMG(imageno); 


DT DFALT 
The DT_DFALT function will perform default entry on one specific field. This func- 
tion must be passed the field pointer and the type of default to be performed. It 
will then execute that type of default for that particular field. The DT IMGIN 
(image in) function applies this function to handle field defaults. Upon detection 
of the default key (defined in the TERMCAP), the DT_IMGIN function calls 
DT_DFALT passing it the current field with the DFALT_ KEY type. DT_DFALT will 
check the default definitions for this field, looking for this type. If one is found 
the default value will be placed at the field address. Due to the fact that the 
DT_IMGIN function addresses these situations, most users will not need to be 
concerned with this level of control. For users who may desire this low level con- 
trol information, the following illustrates how this entry would appear in both the 
d-tree script and your source file. 
d-tree script: 
DEFAULTS(master) 
* Symbol Name Type of defaults Defaults value */ 

custaddress DFALT_KEY Unknown 

Status DFALT_KEY OPEN 


our source file: 


ptr= DT_FLDNM ("status") 
DT_DFALT(fptr, DTDFKEYHIT,tIcol,tlrow); 


oo eeeeeSeSeSeSSSSSSSFSsSeeeSeSsSse 
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The DT_FLDNM function, given a field symbolic name, will return a pointer to 
that field. 

The parameter DTDFKEYHIT contains the numeric value representing the ap- 
propriate default type. The #define statements establishing these values are 
defined in "dt_typdf.h" shown here: 


*/™ default types */ . 
tdefine DTDFTAB 1 default when auto dup key is hit */ 
tdefine DTDFINIT 2 7 default at initlization time »*/ 
tdefine DTDFDUPTAB 3 /* auto dup when auto dup key is hit 7 
tdefine DTDFDUPINIT 4 /™* auto dup at initlization time / 


dt_typdf.h 


RELATED TYPEDEF: 
DTTDFALT 


dt_typdf.h 


alslelaisisislsisisisialsisislaisisisiaisisiaisisisisiaisiaiaiaisiaiaiaieieisi.i.LiLLLLLL LLL LLL LLL Celt eZ 


“4 DFALT definitions 7 

nifdef DTKDFALT 

typedef struct { 

COUNT num; “* default number / 
COUNT dftyp: “™ type of default 7 


TEXT “dftxt: “* pointer to default text 
} DTTDFALT: 


tendif 


MalalalelalsisioiaiaisisiaisioisisialssisiaisisisisisiaisisisieicieicicLLLLLLLL LLL LLL CLL CLC e2 
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7.3 DEFAULTS - Default field values 


THIS PAGE LEFT BLANK INTENTIONALLY 
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7.4 EDITS - Edit a Field 


DESCRIPTION: 
The "EDITS" ability provides the means to define specific edits on particular 
fields along with their associated error messages and other required information. 


SYNTAX: 
EDIT (reference name) 
error message symbol name edit_type —edit_information 


EDITSC example) 

/*4 Error_Message Symbol Edit _Type Edit_Information u/ 
Invalid Field Type cd_fldtyp UALIDATE dt_catud_idx typmap modescan FT 
“¥" or °N’ only alloved cd_resp TABLE Yy Nn 

Field Must Be Entered ta fii MANDATORY 

Entry Already Exists td_version DUPKEY dt_tdnam_idx 


Invalid date MMDDYY ddate DATE_MMDDYY 

Invalid date MMYY tdate DATE_MMYY 

Filed Must Be Filled td_code MAND_FILL 

No Entry in Other SFL ord_itm SFLSAME SFLNAME=sflnam SFLFIELD=sflfld 
Entry found in other SFL cd_fldnam SFLNOTSAME SFLNAME=sflnan SFLFIELD=sflfld 
SFL total does not match ord_amt SFLHASH SFLNAME=sflnam SFLFIELD=sflfld 


reference name 
The "reference_name" must match that of the associated IMAGE and FIELD 
sections. 


Error Message 

The "error_message" contains the text to be displayed on the message 
default line (defined in DT_TYPDF.H by DT MSGLN) when the specified 
"edit_type" is violated. This message is delimited by the symbolic name of 
the field to be edited. Thus, symbolic names are not allowed within the 
edit message. 


Symbol Name 
The "symbol_name' represents the field to be edited. This field must be 
defined in the corresponding "FIELD" section. 


Edit Type 

The "edit_type" contains the valid keyword associated with an edit operation 
to be performed. If data is entered which conflicts with this edit, the 

"error message" is displayed. 

All edit types are described in detail below. 


Edit Information 
The "edit_information" contains additional resources required by specific edit 
types. Note that not all edit types require this entry. 
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EDIT TYPES: 

@ MANDATORY - This field must contain valid data. 

e MAND FILL - Data must completely fill the field. 

e DATE_MMDDYY - The data entered must be in the date format of 
MMDDYY. 

e DATE_MMYY- _ The data entered must be in the date format of 
MMYY. 

e DATE_MMDD- __ The data entered must be in the date format of 
MMDD. 

e TABLE - The data entered will be compared against a table 


of data. The table of data is entered immediately 
following the keyword "TABLE". 
TABLE Example: 


2DITS(custin) 
*Error Message Symbol Name Edit Type Edit Information */ 


Only valid entry is "OPEN" , "CLOSED" or "IIOLD" "status TABLE OPEN CLOSE HOLD 


e DUPKEY - The "DUPKEY" edit provides a means for preventing 
duplicate entries in a file where unique keys are defined. 
Utilizing the provided index symbolic name, a target is 
formed based upon the index segment definition (typically 
this field will be part of that segment definition). Using this 
target, the provided index is accessed to determine if an 
entry of the same value exists. 
DUPKEY Example: 


DITS(addcust) 
*Error Message Symbol Name Edit Type’ Edit Information */ 


hat key already exists cust_ num DUPKEY  custidx 


@ VALIDATE - The validate edit provides the following capabilities: 

1) Insures there is a corresponding entry associated with 
this field in another file. This field is used as the "target' 
to access the associated file via the provided 
index. This index must be defined as unique. 

2) If an associated record is found it allows information 
from that record to be copied (mapped) into other 
fields. See MAP ability description. 

3) Because there must be an exact match between this 
field and an entry in the other file, it provides a means 
by which the user can perform a look-up (SCAN) into 
the other file in order to select a valid entry. 


_—_---————————  ——eeeeesesesSsSeSesesSsSsSe 
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VALIDATE Example: 


=DITS(custin) 
“Error Message Symbol Name Edit Type Edit Information 
nvalid Customer Number cust_num VALIDATE | idxfile codemap codescann prefix 


e "idxfile" - The "idxfile" is the index file to search in validating the entry. 
e "codemap" - The "codemap" is the reference name for the MAP ability 
which performs the copying of information if a match is found. See 


"MAP" ability description. 

e "codescann" - The "codescann'" is the reference name for the SCAN 
ability which performs the look-up. This allows the user to enter the 
‘lookup character (?)" in the field. See "SCAN" ability description . 

e "prefix" - Typically the validate keyword will create a target in the same 
manner as the DUPKEY does. The "prefix" provides a means for this 
target to be prefixed with a literal value. 


e SFLHASH - The "SFLHASH" option will generate a hash total by 
adding the values in a specified subfile’s (GFLNAME) 
field (SFLFIELD) and verify that hash total against the 
value in the field being edited. This edit is typically 
performed when all edits are being performed, prior to 
posting. This overall edit is performed by the function 
DT EDITS. Note: DT_EDITS can be called in 1 of 2 
modes, edit 1 field or edit all fields. Edits on all fields are 
typically performed just prior to a post. See DT_EDITS for 
further information. 

SFLHASH Example: 


‘DITS(trans) 
“Error Message Symbolic Name Edit Type Edit Information */ 
nvalid Hash Total  tot_fld SFLHASH SFLNAME=master SFLFIELD = amount 


e SFLSAME-- The "SFLSAME" option will verify that there is an 
occurrence of the given field (SFLFIELD) in the specified 
subfile (SFLNAME) containing the same value. The 
following example illustrates how the d-tree CATALOG 
program uses this edit to verify that the field name used 
in the creation of an index does in fact exist in the 
"master" subfile. 

ple: 


:DITS(segs) 


“Error Message Symbol Name Edit Type 


“ 
t ‘ ; , 
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@ SFLNOTSAME - The "SFLNOTSAME" option will verify that there is 
NOT a field (SFLFIELD) in the specified subfile 
(SFLNAME) containing the same value. This edit is 
logically opposite to the previous "SFLSAME" edit 
type. The following example illustrates how the d-tree 
CATALOG program uses this edit to insure that an 
index symbolic name is not the same as a field name. 

SFLNOTSAME Example: 


DiTS (trans) 
*Error Message Symbol Name Edit Type Edit Information sl 


‘ield Name Already Exists cd_fldam SFLNOTSAME SFLNAME= master SFLFIELD =cd_ fldnam 


RELATED FUNCTIONS: 
e DTPEDIT- Parsing function which initializes the typedef DTTEDITS. 
e DT_EDATE- Edit routine - DATES. 
e@ DT EDITS- Primary field edit function. 
e DT EDSFL- — Edit a subfile. 
e DT_EDUPK- Edit routine for duplicate keys edit. (DUPKEY) 
e DT EFILL- Edit routine for Mandatory fill edit. (MAND_ FILL) 
e DT_EMAND- Edit routine for Mandatory field. (MANDATORY) 
e DT ETABL- — Edit routine for Table Edit. (TABLE) 
e DT_EVALD- Edit routine - Validate with another file. (VALIDATE) 


TYPEDEF: 
DTTEDITS 


= dt _typdf.h 
Malalsinininisininininisinisinisisisisisisisiaisiai iis eLite LE titi ri ttt rer terre rerereren eta 
“7* EDITS definitions */ 

nifdef DTKEDITS 

typedef struct { 

COUNT edttyp;: type of edit 7 


TEXT *edttxt: pointer to edit message text 
TEXT *addtxt; additional text ™/ 
+ DTTEDITS: 


tendif 


POO OOOO COOOL HALO HOO HO OHO OOO 
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EXAMPLE: 


FairCom 


@CUD 


+Customer Master 


Customer Number: 
Customer Name: 

Customer Address: 
Customer Status: 
Customer Balance: 


Input Attribute Output Attribute Input Order */ 
custnum NUMERIC 
custnam ALLUORDCAPS 
custaddress SCROLL 
custstatus ALLCAPS 
custbal PROTECT 


EDI TS(Cmaster) 

“7* Error Message Symbol Name Edit Type 

Must Enter Customer Complete Number custnum MAND_FILL 
Customer Has Already Been Entered custnum DUPKEY cust_idx 
Status must be “OPEN’ or ‘CLOSED’ custstatus TABLE OPEN CLOSED 


INTERNAL d-tree REFERENCE - DTKEDITS 
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7.5 FIELD - Field definitions 


DESCRIPTION: 

The "FIELD" ability "ties" input fields of an IMAGE to specific DODA entries via 
their symbolic names. The "FIELD" ability uses the name in parentheses _follow- 
ing the "FIELD" keyword (reference_name) to identify which "IMAGE" definition 
these fields are associated with. Each line thereafter relates to a specific input 
field defined on the IMAGE. These definition lines offer a number of options deal- 
ing with input and output attributes, cursor control, as well as I/O field masking. 
Field definition lines must be in the order of their appearance on the screen with 
direction precedence being top to bottom then left to right. 


SYNTAX: 
FIELD(reference_ name) 
/* Symbol Name Input Attribute {Mask} Output Attribute Input Order */ 


FIELD(C example) 
“4 Symbol Name Input Attribute (Mask} Output Attribute Input Order */ 
name FRSUORDCAPS NONE 
address SCROLL EOL 
code TABLE_IN {tt} TABLE_OUT 
menu_item NOCHANGE INPUTRI 
state ALLCAPS NOLINES BLACK YELLOU 
balance PROTECT RI ZERO 


zipcode NONE UL 

phone NUMERIC €(9959)339-8959} --INPUTRI ZERO 
ssn NUMERIC £33S~-S35-39393} RED 

date NUMERIC CXX/“XX/XX} YELLOU 


1 
Z 
3 
4 
5 
6 
contact ALLUORDCAPS BUHITE BLUE ‘a 
8 
9 
18 
il 
time NUMERIC T3351 39'¢95) ZERO 12 


Reference_name-The "reference_name" must match that of the associated 
IMAGE section. 

Symbol _name- The "Symbol Name" is the symbolic name for the associated 
field as defined in the DODA. 

Input Attributes- The "input_attributes" define individual field characteristics 
pertaining to input. The current "input_attributes” are: 


e NONE- No special input attribute is applied to this field. 

e NOCHANGE- The cursor may enter this field but no modifications 
may be made. (This option is typically used in creating 
menus. See "MENUS" description.) 

e NUMERIC- All input for this field must be numeric. Only 0-9, +, - or. 
is valid input for this field. 

e ALLCAPS- All alpha characters keyed at this field will be forced to 
upper case. 

e PROTECT- =‘ The cursor will not enter this field, thus protecting the 
field's data from modification. 

e FRSWORDCAPS- The first letter of the first word keyed in this field 

will be forced to upper case. 
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@ ALLWORDCAPS- The first letter of each word keyed in this field will 
be forced to upper case. (A word is determined 
by a character after a space.) 

e SCROLL - This field will scroll from right to left when the field 
length as displayed on the screen is shorter than the 
actual field length as defined in the DODA. 

e TABLE_IN- The contents of this field will be converted on input to 
another value based upon the "TABLES" definition. 
Requires the use of the "TABLES" ability. 

(See "TABLES" ability.) 


Output Attributes-The "output_attributes" define individual field characteristics 
pertaining to output. The current "output_attributes" are: 


@ NONE - No special output attribute is applied to this field. 

e Ri - This field will be displayed in reverse image. 

e UL- This field will be underlined. 

e INPUTRI - This field will be displayed in reverse image when the 


cursor enters this field for input. (This is the attribute 
used to create the reverse image bar which progresses 
through menu selections.) 

@ NOLINES- = The underline characters, or input guide identifying 
the field position and its length, will not be displayed. 

e EOL - Before the associated field is output that particular 
row in the screen image will be erased from the 
beginning of the field to the end of the line. 

@ TABLE-OUT - The contents of this field will be converted on output 

| to another value based upon the "TABLE" definition. 
Requires the use of the "TABLES" ability. 
(See "TABLE" ability.) 

e ZERO - To be applied to numeric fields. If the value in the 
field is Zero, a zero will be displayed. No underline 
characters, or input guide identifying the field 
position and its length, will be displayed. 

e COLOR ATTRIBUTES- 


e BLACK black e BLUE blue 

e GREEN green e CYAN cyan 

e RED red e MAG magenta 

e BROWN brown e WHITE white 

e GREY grey e LBLUE light blue 

e LGREEN light green e CYAN light cyan 

e PINK pink (light red) e LMAG light magenta 
e YELLOW yellow e BWHITE bright white 


ee eeeeEeEeSeSeeeSeeeeeNSFSFsSsasasesesesesesese 
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Input Order- 


Input Masks- 


exXorx- 


eAora- 
eZorz- 
e!- 
e9- 


7.5 FIELD - Field definitions 


The "Input Order" entry determines the field sequence traveled 
by the cursor upon data entry. By altering these numbers the 
path the cursor travels will change accordingly. 


Input masks present the data field in a more meaningful 
format. The mask must follow a valid input attribute and must 
be enclosed in braces. Any constant characters 

(such as -, /, etc.) may be used within the mask intermingled 
with valid masking characters. Valid masking characters are: 
Anything within the regular character set is accepted 

(no special control characters). 

Alpha only. 

Everthing is accepted (special control characters included). 
Convert to upper case. 

Numeric only. 


Example Masks: 
{(999)-999-9999} example phone number. 


{99:99:99} 
{!!} 


example time. 
example first two characters are upper case. 


{999-XXXX } example code field. 


RELATED FUNCTIONS: There are a number of functions which work with 


fields. The following are only the primary field-related 
functions: 


e DIPFIELD - Parsing function which initializes the DTTFIELD typedef. 
e DT FLDIN- Input a field. 

e DI FLDLO- Field out - low level 

e DT FLDNM - Validate token as valid field symbolic name in DODA. 

e DT FLDOT - Display Field (Field Out). 

e DI FLDTX- Convert an Ascii Field to Valid Field Type. 

e DI DFALT - Default a specific field value. 

e DT EDITS-_— Edit a field. 

e DT HELPP -_ Provide help for a field. 
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TYPEDEF: 
DTTFIELD 


dt_typdf.h 


Aaa sinisisinininininiainisiaisinisisisisisisisininissisistsinialislbiticltciListh thi tet tT ieTrTereTtieieTeett ee oe 
7“ FIELD definitions / 
ifdef DTKFIELD 
typedef struct { 

DATOBJ *fdoda; 

COUNT fFdodano;: 


COUNT len; 


COUNT inpatr: 


COUNT outatr{€DT_MXOAT]I: 


COUNT col; 
COUNT row; 
COUNT dec: 


COUNT hooks: 

TEXT *innmask; 
TEXT *outmask: 
wifdef DTOLDHOOK 
DT_FPTR funcptr: 


tendif 
+ DTTFIELD;: 


teondif 


7% 


pointer to doda 

doda number 

length displayed on screen 
input attribute 

output attribute 

column number for display 
row number for display 
decimal positions 

hook bit mask 

input mask 

Output mask 


special function 


*/ 
*/ 
eZ 
x7 
*/ 
7 
x7 
*/ 
7 
nw 
a7 


“S 


Aeisititinisiaitisisisinisisiisisisisisisisisinaisisiainininiaiisiaiaiisisisi LOL Cee 


EXAMPLE: 


IMAGEC master?) CLSTFLD_ADVANCE} {FRSFLD_BACKUP} 
FairCom 
Customer Master 


SDATE 


Customer Number: 


Customer Name: 


Customer Address: 
Customer Status: 


®CWD 


renee ree ee 
nee 
f Rreteet 


Customer Balance: 


IELD( master) 

* Symbol Name 
custnum 
custnam 
custaddress 
custstatus 
custbal 


Input Attribute {Mask} 


NUMERIC 


ALLUORDCAPS 


SCROLL 
ALLCAPS 
PROTECT 


RI 

NONE 
NONE 
NONE 
NONE 


INTERNAL d-tree REFERENCE - DTKFIELD 


Output Attribute 


Input Order */ 


_ eee 
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7.6 GROUP - Group Abilities 


DESCRIPTION: 
The "GROUP" ability provided a means to "group" ability definitions. An ability 
definition in its parsed "memory format" is known as an ADAM. (see section 4 
for ADAM discussion). Once multiple ADAMS are grouped, they can be written 
from memory to disk, formulating an "ability dictionary". An ability dictionary is 
a C-tree variable length file that can contain multiple groups. A group is a related 
set of ability definitions (ADAMS). The concept of a disk file containing "memory- 
ready" definitions provides a powerful alternative to traditional programming 
techniques. Data indepedent logic flow can now be written, where the abilities 
(screens, edits, fields) are no longer hard coded into the program, but 
“swapped in and out of memory" from the "ability dictionary". 
GROUPS provides an effective approach to: 

e 1) relate ability definitions. 

@ 2) control swapping definitions ("groups") in and out of memory. 

e 3) control memory utilization which is especially useful with large 

d-tree scripts. 

SYNTAX: 
GROUP (reference name) {FILENAME =filename} 


GROUP(groupname) {FILE_NAME="ability. dic} 


"reference name" must be present to uniquely identify this particular set 
(GROUP) of parsed ability definitions. There are no prerequisites or 
dependencies placed upon this entry. 


"{FILENAME = filename}" - The "FILENAME" keyword Is optional. If present , 
the "filename" entry is used to identify the name of the c-tree variable length file 
to be used as the “ability dictionary". If no filename is specified, a default file, 
named DTGROUP.SWP, will be used. 


Let's discuss further how this feature actually works. As explained in section 4, 
Parsing a d-tree script results in an allocated block of memory that is initialized 
with the script definition for each ability: an ADAM. Logically, the larger the d- 
tree script, the more memory required to hold all the resulting ADAMs. The 
GROUP ability provides a way to maintain the current parsed ability definitions 
so that memory can be "freed" to provide additional space for other ADAMs. 
This is accomplished by placing “logically related abilities" together in the d-tree 
script, followed by the GROUP keyword. When the parsing function encounters 
the GROUP ability section, it will copy all ADAMs currently in memory (in their bi- 
nary form) to the the c-tree variable length file. The memory previously occupied 
by those ADAMs is then freed. The parsing process will then continue with 
memory utitilization reset back to where it was when the parsing process started 
(as if you where starting to parse a new script). 


NL Se ER Sips ESS SSSA GSD SGD Ss SS sisinammliisiecsiimias? 
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Remember: when the group keyword is encountered, the definition is saved to 
disk and memory is freed. Any definition that has been written to disk that is 
needed by the program must be "swapped-in" before it is used. This is done 
with the group in function: DT_GPINN. If the last set of abilities in a d-tree script 
have been "grouped" (the last keyword found in the script is the GROUP 
keyword), then after the parse is complete, there is nothing in memory that 
reflects any of the definitions found in the script. All definitions now reside in the 
"ability dictionary(ies)". The group out function (DT _GPOUT) is the function 
called by the parsing routine to write the definitions to disk. 


RELATED FUNCTIONS: 
e DTPGROUP - Parsing function. 
e DT_GPINN- Read a GROUP in from disk. 
e DT GPOUT - Write a GROUP to disk. 


TYPEDEF: DTTGROUP 
dt_typdf.h 


A itt eet eet EE EP Eee eet eee ttt etitt tt ttt ttt ttt tt ttt rtt tt ttt Pa 
7% GROUP definitions */ 

ifdef DTKGROUP 

typedef struct { 

COUNT num; 7™* group number “/ 
POINTER recbyt(DTKLASTI; 7* record byte position in file */7 


TEXT filename(MAXFIL]: /* disk file name for group */ 
+ DTTGROUP:; 


tendif 


7, ¥4 4 D4 DE DE DE DE DE DE DE DE DE DE DE Dk DE DE Dd DA Dk DE DE DE DE DE DE Dd Dd DE DE De HE Dk DE De DL Dk Dk Dk DE kk De Dk ek ke ke Bd 


EXAMPLE: 


IMAGE( file changed) {LSTFLD_ADUANCE} {BASE_ROW=12} {CLR_BLOCK} 
+File Definition Has Been Changed 


Is this a (Neu version of the file 7? 


or 
If so old definition WILL BE LOST. 


(Ndeu or (Replace =: __ 


FIELD( file changed) 
7* Symbol Name Input Atribute Output Atribute Input Order I/O Mask */ 
menul ALLCAPS NONE 1 7* source file name */ 


EDITS( file changed) 

Must Enter (N) or CR) menul MANDATORY SSS SS SSS SRNR 

Must Enter (N) or €R) menui TABLE N R The ADAM created from these 
ability definitions will be 

GROUP( file changed) {FILENAME="filchang. sup’}]] uritten to this disk file and 


the memory it occupied will be 
an ee cleared. 


INTERNAL d-tree REFERENCE - DTKGROUP 
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7.7 HELP - Help Text 


DESCRIPTION: 
The "HELP" ability provides a means to nee help information for specific 
fields. 


SYNTAX: 

HELP(reference name) 

USES SFL(subfile reference name) 
Help Text or Token fields 


HELPC master) 
USES_SFLCmaster) 
“* Help Text or Token fields a7 


Place Y or N Here. prtfield +#—____—_—_—— Method #1 
helpl addressl addressZ2 <+—— Method 82 


"reference_name" - The "reference" identifier is used to uniquely identify the 
HELP section. This section is not dependent upon any other ability section. 


There are two methods in which help text may be displayed: 


e Method #1- A single line of text displayed on the "default message 
line". (See #define DT_MSGLN in DT_TYPDF.H.) 

e Method #2- Pages of text which may be displayed In a scrollable 
region on the screen. (subfile) 


"USES_SFL"- (Method #2 only) - The "USES SFL" entry is optional. This 
entry is only used if help text is displayed using a scrollable 
region of the screen (A subfile). The "USES SFL" keyword 
must be followed by a "(subfile_reference_name)" -This is the 
name of the subfile which is loaded with the help text from the 
help text file. This subfile must be previously defined within a 
SUBFIL ability section. See "SUBFIL" ability. 


"help text or help token 


Within this entry position you may enter one of two different entries, 
help_text or a help token. Enter a single-word identifier to access your help 
file, method #2, or enter a multiple-word string of help text to be displayed, 
method #1. The help parsing function (DTPHELP) determines which 
method of help you are using via the following logic. First, it reads the entry, 
searching for a valid symbolic field identifier to know when it has reached - 
the end of this entry. If only one word is found by the parsing function when 
a valid symbolic field identifier is encountered then that single word is 
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assumed to be a help token. Thus, method #2 is being used. If more than 
one word is identified within this entry, this string is considered to be help 
text and method #1 is used. 


"help_text" - (Method #1 only) - The “help text" is the actual text to appear 
on the screen when help is requested for the associated "field _sym- 
bol_name". As noted earlier, a single word is identified as a help token, 
therefore, help text must be at least two words in length (separated by at 
least one space). Since the parsing function delimits this entry via a valid 
symbolic field identifier, symbolic field identifiers are not allowed to be 
buried within the help text. 


"help_token" - (Method #2 only) - The "help token" is the identifier used to 
access the associated text from the users help text file. Using this token as 
the identifier, the associated text is loaded into the defined subfile which is 
then displayed to the user. This token is the target used for a c-tree FRSSET 
Call. 


“field_symbol_name" - (Method #1 and #2) -The “field symbol_name" is 
the symbol name(s) as defined in the DODA for which the help information 
is to be applied. This entry is required for both help methods. 


NOTE: When defining help for a field, the help text is assigned to a DODA ele- 
ment. Therefore, help placed on a specific field is available to that field even 
when positioned on multiple screens. 


RELATED FUNCTIONS: 
e@ DIPHELP - Parsing function which initializes DTTHELP typedef. 
e@ DI HELPP -_ Help routine. 
e DT BHELP- Build help file index. 


TYPEDEF: 
DTTHELP 


dt_typdf.h 
7. V4 4 4 DE DEED DED Dk DE Dk Dk DD Dk DE Dd Dd DD Dk Dk Dd kk Dd ek 
7* HELPP definitions »/ 
ifdef DTKHELPP 
typedef struct { 
num; help number */ 
sfino: subfile number 7 


fdodano: doda field number */ 
*string:; help text or help token */ 
+ DTTHELPP; 


tendif 


7, 94 HEHE D4 DEDEDE DEDEDE DE DE D4 DE De DE Dek DE DE DE DE DE Dk DEE DED DEE DE Dd Ded Dk Dk oe ED Dkk De DE ae ek kd at td” 


titi Dia stale cg ein casei aga ip asa gg Bt | BIE EE ETE 
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EXAMPLE: 


IMAGEC master) {(LSTFLD_ADVANCE} {FRSFLD_BACKUP?} 
@DATE FairCom 


@CUD 
+Customer Master 


Customer Number: 
Customer Name: 

Customer Address: 
Customer Status: 
Customer Balance: 


FIELD(C master) 
“* Symbol Name Input Attribute Output Attribute Input Order I1/0 Mask 
custnum NUMERIC 
custnam ALLUORDCAPS 
custaddress SCROLL 
custstatus ALLCAPS 
custbal PROTECT 


IMAGEChelptitle) (CLR_BLOCK} 


HMAGEC help) {NO_CLS} {CLSTFLD_ADUVANCE} {FRSFLD_BACKUP} 


“IELD( help) 
“ Symbol Name Input Attribute Output Attribute Input Order [70 Mask 
helpl NOCHANGE NOLINES' 1 


SUBFILEC hel p) 
»9FL_IMAGEC help) 

>FL_RECORDSC 25) 

SFL_LINES(S) 

FL_TITLEC helptitle) 

>FL_ BOUNDARY 

* doda first field doda last Field *7Z 


elp elp 
HELP( master) 
USE ( 


elp) 


~ 
A customer number must be placed in this field. custnum 
HELP1I custname 
HELPZ custstatus 
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HELP TEXT FILE ACCESS 


d-tree provides the capability of building an index over a standard text file. This 
capability is used by the HELPP ability in method #2. By creating a normal 
ASCII text file containing help text and using unique tokens to identify each sec- 
tion of help text, d-tree provides the means of building an index file over the 
help text file. 

The basic steps in building a help text file and its index are: 

@ Key the help text into a file. This may be accomplished by using your 
favorite text editor. Help text for each field should be in separate 
groups. 

@ Insert tokens. Each field’s group of text should be uniquely identified 
by a token enclosed in the token delimeters. (The default delimeters 
are {}). 

e Verify filenames. Both the help text filename (help.txt) and the help text 
index filename (help.idx) are determined within the header file 
dt_typdf.h. If you elect to use names other than these defaults, the 
#define statements within this header file should be edited to reflect 
the proper filenames. 

e The program DT_BHELP must be executed. This utility will build the 
index over the help text file. 


The "help file" is simply a standard ASCII text file containing all the help informa- 
tion for each field. The help information for each field should be identified by a 
unique token enclosed in the defined token delimeters. The default token 
delimeters are the open and closed braces ({}). The default length of these 
tokens is 36 characters. The token delimeters along with the maximum token 
length, help text filename and help text index filename may be altered by edit- 
ting the header file dt_typdf.h. 


dt_typdf.h 


tdefine DTHLPFIL “help.txt" 7“ help file data name »*/ 
tdefine DTHLPIDX ~™ : i “7* help file index name »*/ 
tdefine DTHLPTKL 7* help token length */ 


tdefine DTHLPLDL ’ {’ “7* help token left delimiter */ 
rdefine DTHLPRDL ’}’ 7* help token right delimiter */ 


Once the help text file has been made, d-tree must build an index file over this 
help text file for efficient access. This help text index file is constructed by the 
program dt_bhelp (build help). This utility will first read the entire text file and 
construct an index key for each token found. Any time the help text file is al- 
tered this utility must be rerun to rebuild a new index file for the new version of 
the help text file. 


eee 
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This key entry assembled in the c-tree index file is defined as follows: 


a dt_bhelp.c 
| 


c-tree index entry has tuo parts 


| | 
| sa RANE Anca ecient 
| Canything) | Clong integer) | 
| | 


target portion H recbyte portion 

| 

7 | 

| 
XXXXX@1234 | 
eG ac paric a aie target. | 
ane err Tre gegen ee NULL byte ‘i 
i ce eee eee length of text | 


~ 


the recbyt portion of the c-tree index is the 
offset uithin the text file that the text resides. 
“/ 


When a single "help_token" is defined in the d-tree script (method #2), it is used 
as the target in a c-tree FRSSET call. As shown above, access to the index 
entry provides not only the offset within the text file where the text starts, but 
also the length of the text. The ODT HELPP function reads this text and formats 
the text to the dimensions of the associated subfile. This subfile is then dis- 
played (DT _SFLOT), presenting the help Information to the user. 


NOTE: You may find this capability of building an index over a standard text file 
a very useful tool in other appplications. See DT_HELPP.C and DT_BHELP.C. 


INTERNAL d-tree REFERENCE -DTKHELPP 
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THIS PAGE LEFT INTENTIONALLY BLANK 
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7.8 HOOKS - User Hook into d-tree 

DESCRIPTION: 

The "HOOKS'" ability allows the user to provoke a call toa 

"user defined function" at a specific "hook location" based upon specified 
conditions. 


SYNTAX: 
HOOKS (reference _name) 


“* Hook Symbol Name 
BEFORE_INPUT 


Condition Function Name Parameters */ 
cur_field=amount DO_MAP mapsub 


AFTER_INPUT cur_f{ield=amount DO_MAP SHOU mapsub 
AFTER_INPUT cur_field=amount AND cur_image=1 DO_MAP SHOU mapsub 
AFTER_INPUT cur_field=amount OR cur_image=master DO_MAP SHOU mapsub 
AFTER_ 


INPUT cur_field=amount AND cur_keybd=F1 DO_MAP SHOW mapsub 


/* Hook Symbol Name Condition Function Name Parameters */ 


"reference_name" - The "reference_name" is required and must be a 
unique identifier for this HOOKS ability definition 
section. No prerequisites or dependencies apply to 
this entry. 


"Hook Symbol Name"-defines the location in the logic flow where a user- 
defined function is to be called if the proper conditions 
are met. The hook ability has been designed to allow 
the user to add their own hook locations. The steps 
to add a new hook location are explained in section 9. 
During the definition of a hook location an associated 
"Hook Symbol Name" is established. This is the 
symbol name entered here. The following are the 
currently defined hook locations: 


e BEFORE_INPUT-This hook is located just before a control is given to 
the user to enter data into the current field. 


e AFTER_INPUT - This hook is located just after control returns from 
the user when entering data into the current field. 
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"Condition" - The "Condition" establishes the qualifying criteria which must 
be present before the user function is to be called. d-tree has 
predefined the following conditions: 


e "cur_field=" - the cursor must be positioned within the field reference 
by the cur_field before the condition is determined as true. 

e "cur_image=" - current image accepting input must be the same as 
the image defined by cur_image before the condition is determined as 
true. 

e "cur_keybd =" - the last key pressed on the keyboard must be the 
same as defined by the cur_keybd before the condition is determined 
to be true. 


(See section 9 to add additional conditions) 


The "Condition" entry is allowed to contain boolean (AND/OR) logic. 

For example: If you only wish to call a specific user function when a specific 
image (image "master" in our example) is displayed and the user presses a 
specific key (F1 in this example). This "Condition" entry would appear as fol- 
lows: 

cur_image =master AND cur_keybd=F1 


Note: The ADD/OR logic does not support complex expressions. They are 
simply evaluated from left to right. 


"Function Name'"- is the name of the user function to be called. This 

function name must appear as an entry within in the 
“user defined function table", DTSFUNCT. This table 
must be defined in every program that calls user defined 
functions and must be of type DTTFUNCT. This table is 
used to validate the function name as well retrieve a 
pointer to be used to call the function. The following is 
a sample user-defined function table. 

“7* Valid User defined special functions */ 

DTTFUNCT DTSFUNCT() = {€ 

{ “DO_MAP’, DT_CALMP }, 


{ “DT_VERT’, DTCATURT }, 


C DT_NULFP } 7* terminaton Indicator (MANDATORY) 7 
+; 


“Parameter'- All user-defined functions are passed a pointer of character 
type (char *) which points the the text defined here in the 
script. All text following the conditions are passed as a String. 
The user-define function is responsible for interpreting the 
information passed in this string. 


—— eee 
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RELATED FUNCTIONS: 
e DTPHOOKS - Parsing function which initializes DTTHOOKS typedef. 
e DT_ HOOKS - Primary HOOKS function. 


TYPEDEF: DTTHOOKS 


dt_typdf.h 
ye tt tt tt tt tt te ee tee et a ee te ee ttt ee tt ttt tet ttt tte tt tt tt tt tt 33-3 t-t-¢-t-t-1-1-1-3-94 
“* HOOKS interface definitions 7 
tifdef DTKHOOKS 


typedef struct { 

COUNT num; “7* hook number */ 

COUNT spot; 7* location (spot) in code where hook occures */ 

COUNT if_abil: 7 ability reference number-current ability to check»/ 
COUNT if_ocur; 7* ability occurance number-if current ability is this»/ 
DT_FPTR funcptr: 7“* hook function pointer */Z 


TEXT *parms: 7™* function parameters 7 
+} DTTHOOKS: 
tendif 


a tlt telelalatolatatalatstatatatatalalatalalalataialatatalalaiaiaielaistalataiateiaioieieicietisteiei.ieiet.i.t.i.ittit.iit ita 


DTTFUNCT - user define function table typdef. 


“4 USER Defined Functions 7 
typedef struct ¢€ 


TEXT Mname: “* function name 7 
DT_FPTR funcptr: ““ function pointer to user function u/s 
>} DTTFUNCT: 


EXAMPLE: One of the most common uses of hooks occurs when you want to 
accumulate one field from information entered into another field . In the catalog 
program, we add up the index length as each index segment is entered. Han- 
dling this type of approach involves backing out the "old" value of the field, and 
then adding in the "new". In the following example we define a BEFORE_INPUT 
hooks to back out the old, and then an AFTER_INPUT to add in the new. The 
user-defined function DO_MAP uses the MAP and CALCS abilities to perform 
the data manipulation. 
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EXAMPLE: 


IMAGEC index) {NO_CLS} {LSTFLD_ADVANCE} {FRSFLD_BACKUP} 


FIELDC index) 
7% Symbol Name Input Attribute Output Attribute Input Order */ 
id_idx NONE NONE 
ikeylen PROTECT NONE 
ikeytyp NONE NONE 


/*index nameX/ eg 
7* key length»*/ 

7* key type 

7“ duplicate flag*/ 

7% null key flag*/ 

7* empty character*/ 

7* index file modex/ 

7/* index file ext sizex/ 

7* index file namex/ 


ikeydup ALLCAPS TABLE_IN TABLE_OUT 
inulkey ALLCAPS TABLE_IN TABLE_OUT 
iempchr NONE NONE 
id_ifilmod NONE NONE 
id_ixtdsiz NONE NONE 
id_idxfil NONE NONE 


WONTDU AWN 


IMAGEC segs) {NO_CLS} {LSTFLD_ADVANCE} {FRSFLD_BACKUP} CBASE_ROW=14} 


FIELD( segs) 

7* Symbol Name Input Attribute Output Attribute Input Order */ 
sd_col NONE NONE 1 /“*column/ 
soffset NONE NONE 2 /*segment offset/ 
slength NONE NONE 3 /*segment length*/ 
segmode NONE NONE 4 /*segment modex/ 


CALCS( segcalc_sub) 
ikeylen — slength 


MAPC segmap_sub) | 
7* source field desination field Map Type length »*/ of 
segcalc_sub ikeylen DO_CALC 


CALCS( segcalc_add) 
ikeylen + slength 


MAPC segmap_add) 
7* source field desination field Map Type length */ 
segcalc_add ikeylen DO_CALC 


HOOKS( segs? 

7* Hook Symbol Name Condition Function Name Parameters 7 
BEFORE_INPUT cur_field=slength DO_MAP segmap_sub 
AFTER_INPUT cur_field=slength DO_MAP SHOU segmap_add 


The next example shows how to provoke a user call when processing a certain 
image if a certain function key is hit: 


HOOKS( trans)? 
“* Hook Condition Function Name Parameters */ N / 


AFTER_INPUT cur_image=master AND cur_keybd=F11 DT_VERT 1 
AFTER_INPUT cur_image=master AND cur_keybd=F12 DT_VERT = 


INTERNAL d-tree REFERENCE - DTKHOOKS 
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7.9 IFILS - Incremental Files 


DESCRIPTION: 
The "IFILS" (Incremental Files) ability provides a means to define file(s) and 
index(es) definitions from a d-tree script. IFILS are used in two ways: 


SYNTAX: 

IFILS or  IFILS 

DICTIONARY filename FILE NAME filename 

FILE NAME filename KEY NAME indexname 

FILE VERSION version KEY FIELDS field_symbol(s) DUPS_OK 


FIRST _VLEN field_symbol 
IFILS 
DICTIONARY data_dictionary 
FILE_NAME file name ——_—_——-| Data Dictionary Approach 
VERSION file version 


IFILS 


FILE NAME data_file name 
KEY NAME key symbol _ name —————-| Run-Time Approach 
KEY _ FIELDS field symbol(s) DUPS_OK 


FIRST_ULEN field symbol 


IFILS provides the necessary file and index definition needed to access the data 
base. The method to use (or to use IFILS at all) depends upon the manner 
chosen to define the files. Consider the following manners by which files can be 
defined: 


NOT IN d-tree Script - Files and index definitions can be defined in the program 
either in the form of hard coded incremental files structures or by the use of 
parameter files. These are the primary methods to define files and index(es) In 
c-tree, in which case, the IFILS keyword is NOT applicable. 


IN d-tree Script- 

Data Dictionary Once data file and index definitions have been entered 
into a data dictionary (Catalog Program), these file definitions can be accessed 
by programs using the IFILS keyword. Following the IFILS keyword in your 
script enter the word "DICTIONARY" with an optional file name. (d-tree will 
default to the catalog’s data dictionary file name if no alternative file name is 
provided). Indicate the file of choice with the "FILE NAME" entry. The 
"VERSION" keyword is optional. If provided it will qualify the precise file. If not 
provided, access to the data dictionary will be done with a LSTSET (see c-tree) 
retrieving the last version (assumed to be the most current) of the file. This will 
directs d-tree to the source of the file and index definitions. The call to DT_IFILS 
in the program will detect this definition, access the data dictionary, and initialize 
the program with all file and index necessities, including: DODA, IFILS, IIDX, and 
ISEG structures. NOTE: Make IFILS the FIRST ability in your script. 
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IN d-tree Script- 

Run-Time Definitions: As you have seen with the "RUN" program, the d- 
tree tools have the ability to create file definitions at run-time soley from the d- 
tree script. Let’s talk about how this is done. When an IMAGE keyword is en- 
countered while parsing a d-tree script, a determination is made if there are any 
file definitions at this time (it checks to see if a DODA already exists). If not, it 
will build a DODA while parsing, based on the fields found in this IMAGE sec- 
tion. Field names default to F001, F002...etc. The DODA provides the fields and 
the record length to the program, but this is not everthing that is needed to 
open a file. The IFILS keyword in this case is used to supply the additional infor- 
mation to complete the file and index definitions: 


FILE NAME - provides the data file name on disk to access. 

KEY NAME - provides the index symbolic name. 
The first occurence of this entry is considered the primary key 
while following entries are considered secondary keys 
(members). The "symbolic_key_name" entry will be the 
symbolic name assigned to the index. 


KEY_FIELDS - _ identifies the field or fields to be used as the key. The 
first occurance of a "KEY FIELDS" entry is considered the 
primary index while subsequent occurences are index 
members. The “symbolic_key_field_name(s)" must be a valid 
symbolic field name(s) identifying the key segments. 
The "DUPS_OK" option informs d-tree that duplicate keys are 
allowed and c-tree duplicate key logic is to be used. This entry 
is optional and must follow the last field (segment) symbol. 


FIRST_VLEN - option identifies that this file is to be defined as a variable 
length file. The "symbolic_field_ name" following the 
"FIRST _VLEN" option must be the symbolic name of the first 
variable length field. 


The "RUN" program defaults these values when it creates the d-tree script. 
Using the option as above the user can modify the script to: add additional 
keys; change key segments; make the file variable length: change the index or 
data file names on disk; change index symbol names: change field names. 
NOTE: because the files were already created the first time you ran the "RUN" 
program, if a change is made, the files must be deleted before the program is 
run again. This will allow "RUN" to re-create the files with your new definition. 


Because the doda is built based on fields found in an IMAGE section if no pre- 
vious DODA is found, this method only supports one data base file at a time. 
d-tree only uses this method in the "RUN" program at this time. We do not ex- 
pect or encourage this approach in your normal development. As with the 
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"RUN" program, we can see a use for this for "get up quick" or "RUN type" 
programs. The dynamics involved here are interesting. In one way this "run-time" 
file definition can be thought of as a VIRTUAL file approach, a concept bound to 
mature in future releases. 


RELATED FUNCTIONS: 
e DTPIFILS - Parsing function which initializes the DTTIFILS typedef. 
e DT_IFILS - Function to initialize file definitions and open files. 


TYPEDEF: 

DTTIFILS 
sone ce ctifil.h 
tdefine DAT_EXTENT mere: a 
tdefine IDX_EXTENT “ae 


typedef struct {seg { 
COUNT soffset, “* segment offset *7 
slength, “* segment length ™/Z 


segmode;: “™ segment mode a7 
} TSkG: 
typedef struct iidx ¢ 
COUNT ikeylen, 7“ key length m7 
ikeytyp, “™ key type M/s 


ikeydup, “™ duplicate flag */ 
fnulkey, 7™ null ct_key flag ™/ 


fempchr, “* empty character “7 

inumseg: 7 number of segnrents mS 
ISEG “seg: 7* segment information 7 
TEXT Mridxnam: 7 r-tree symbolic name 7 
> IIDX: 


typedef struct if il ¢ 
TEXT Mpfilnam: /7™ File name (u/%o ext) 7% 
COUNT dfilno: “4 data File number ¥Z 
UCOUNT dreclen;: 7™ data record length al 
UCOUNT dxtdsiz: /“™ data file ext size “7 
COUNT dfilmod: “™ data file mode 7 
COUNT dnumidx: “™ number of indices 7 
UCOUNT ixtdsiz: “™ index file ext size */ 
COUNT ifflmod: “* index file mode m7 
IIDX Mix: “™ index information 7 
TEXT rfstfld: 7™ r-tree ist fld name */ 
TEXT Mrlstfld: 7 r-tree last fld name 7 
COUNT tfilno:; 7“ temporary file number 
> TF: 
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EXAMPLE: 


IFILS 

DICTIONARY datad.dat 
FILE_NAME myfile.dat 
VERSION 1.@ 


IMAGE( master) {LSTFLD_ADVANCE} {FRSFLD_BACKUP} 


@DATE FairCom 


Customer Master 


@CUD 


+ 


Customer Number: 3 


Customer Name: 


Customer Address: 
Customer Status: 
Customer Balance: 


FIELD( master) 


7“ Symbol Name Input Attribute Output Attribute 


F@GG1 NONE NONE 
FQ88Z2 NONE NONE 
F8883 NONE NONE 
FG864 ALLCAPS NONE 
F@88S PROTECT NONE 


INTERNAL d-tree REFERENCE - DTKIFILS 


LL 


@TIME 


Input Order 7 


eee 
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7.10 IMAGE - Screen Image 


DESCRIPTION: 

The "IMAGE" ability provides the means to define screens (images) to d-tree. 
Variable input fields, constant output fields, and special effects such as frames 
are defined in a WYSIWYG syntax in the d-tree script. 


SYNTAX: 
IMAGE(reference name) {option1} {option2} ... 


U_BA UJ 


FairCom 


@®CUD 


+Customer Master 


Customer Number: 


Customer Name: 

Customer Address: 
Customer Status: 
Customer Balance: 


A screen is defined in d-tree by means of the IMAGE ability. Enter the keyword 
IMAGE along with a reference name to start the screen definition. 


"(reference name)" - This entry must be a unique IMAGE section Identifier 
and must match the reference _name of a FIELD section 
if input fields exist on this screen Image. 


Optional "IMAGE level" attributes may then be defined by placing the attribute 
keyword with { } after the IMAGE keyword. These attributes are described 
below. The first line after the IMAGE keyword Is line one of your screen. Paint 
your screen observing the following points: 


e Constant fields are keyed just as they are to appear to the user. 


e Variable Fields are defined by using multiple underscore characters 
(_) and must be delimited on both sides by a white space (ie: blank, 
new line, tab, cr). Note: the (_) is a #define in ot_typdf.h. 


e Floating point variables properly display the decimal precision by 
placing a decimal point at the appropriate location within the (_)’s. 
Example: 
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e The "IMAGE" ability has other special features. By placing these 
optional entries anywhere within your screen the corresponding system 
information or feature will be displayed: 

@Date —_ display the System Date. 

@Time display the System Time. 

@CWD _ display the Current Working Directory. 
(see dt _const.c to add your own special @) 


FRAMES: 


+ 1..9 - Frame definition. By placing two plus signs (+) on the 
screen image you may define the top left and lower right 
corners of a frame. Up to nine boxes may be defined ona 
single screen image. If only one is defined, the number one 
after the plus sign is optional. 

Frame Options: 
Frame Title- To center a title in the top line of the frame, 
simply key the title immediately following the top left 
corner plus sign. 
Frame Sides - Which sides of a frame you want to be 
displayed can also be controlled. If no special control 
is placed on the frame, all four sides are presented. 
The keywords {TOP} {BOTTOM} {RIGHT} {LEFT} can 
be placed directly after the bottom right plus sign (+) 
to specify the sides to display. 
Frame Types - More than one frame type can be defined 
in the TERMCAP file as long as it only takes a single 
byte to define the frame character. Terminals that 
‘require a multi-byte sequence to display a frame 
character can only support one frame type. DOS 
environments typically only need one character, so the 
terminal definition in the TERMCAP file for DOS terminals 
have four different frame types. (ie: single bar, double bar, 
combination bars). To specify the frame type in the 
IMAGE section enter {FRAME TYPE =X} where 
X = a number from 1 to 4 for the desired frame type. 
See ex_popup.c in section for for example. 
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"IMAGE LEVEL" OPTIONAL KEYWORDS: 


e NO CLS - The "NO _ CLS" option specifies that the screen should not 
be cleared before displaying the image. 


e LSTFLD_ADVANCE - The "LSTFLD_ ADVANCE" option directs the 
program flow to exit the input loop when a "CR" is encountered while 
the cursor is positioned within the last field on this image. 


e FRSFLD_BACKUP - The "FRSFLD BACKUP" option directs the 
program flow to exit the input loop when the cursor is positioned in the 
first input field and the backup key is pressed. 


e INPUT ADVANCE = {n fields} or {key} - The "INPUT ADVANCE" 
option directs the program flow to exit the input loop when a specified 
number of fields are input or a specified key is pressed. 


e CLR_LINES = {n} - The "CLR _LINES" option will clear the specified 
number of lines from the base of the image being displayed. 


e CLR_BLOCK - The "CLR_BLOCK'" option will clear only the block of 
the screen that Is used by the Image being displayed. 


e CLR_EXIT - The "CLR_EXIT" option will clear only the block of the 
screen that this image uses upon exiting the screen. 


e POP_UP - The "POP_UP" option will clear only the block of the screen 
that this image uses before it is displayed and will then initialize all 
resources utilized by the DT_UNPOP function. DT UNPOP will clear 
the current pop-up image and refresh any previously displayed images. 


e BASE_ROW = {n} - The "BASE ROW" option determines the row for 
the top edge of the image being displayed. 


e BASE_COLUMN = {n} - The "BASE COLUMN" option determines the 
column for the left edge of the image being displayed. 


e BACKGROUND = {color} - the "BACKGROUND" option will set the 
background color (DOS). 


e FORGROUND = {color} - The "FOREGROUND" option will set the 
foreground color (DOS). 
(NOTE: Color keyword definitions are found in the Output Attributes 
definitions of the FIELD ability.) 
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RELATED FUNCTIONS: 

@ DTPIMAGE - parsing function. 

@ DT_IMAGE - IMAGE OUT then IMAGE IN. Combination DT_IMGOT 
then DT_IMGIN. 

@ DT_IMGAL- IMAGE ALL - Display and Input a range of IMAGEs. 

e@ DT_IMGIN- Input an Image (Image In). Series of DT_FLDINs related 
to the provided IMAGE. 

@ DT IMGLG-_ Redisplay IMAGEs from log. 

@ DT_IMGMV- Same as DT_IMAGE but allows user to change IMAGE 
coordinates. 

e DT_IMGOT - Display IMAGE (Image Out). Series of DT FLDOT and 
DT CONST related to provided IMAGE. 


TYPEDEF: 
DTTIMAGE 


dt_typdf.h 


7. V4 D4 W444 4 D4 D4 DE DEH DE DE DE DE DE DE DE DD BD DD DD dk ke 
7* IMAGE definitions */ 

ifdef DTKIMAGE 

typedef struct { 


COUNT num; “7* image number “7 
COUNT e253 7* clear screen flag 7 
COUNT lstcr: 7* exit on last field carride return m/ 
COUNT fstbu:; 7* exit on first field backup aS 
COUNT inpno;: 7* if this many fields have been entered then exit */ 
COUNT topcol; 7* Top left corner column for display */ 
COUNT toprouw: 7* Top left corner row for display */ 
COUNT basecol; /* Top left corner column from parse / 
COUNT baserouw; 7* Top left corner row from parse */ 
COUNT noofvar:;: 7* number of variable fields “7 
COUNT noofcon; 7* number of constant fields */ 
COUNT fstrou: 7* first rou */ 
COUNT lstrou; 7* last row / 
COUNT lftcol; 7* left most column / 
COUNT ritcol;: 7* right most column / 
TEXT *varptr:; /* first variable relate ptr */ 
TEXT *conptr;: 7* first constant relate ptr “/ 


+ DTTIMAGE: 


ee 
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EXAMPLE: 


@DATE FairCom 


@CUD 


+Customer Master 


Customer Number: 
Customer Name: 
Customer Address: 
Customer Status: 
Customer Balance: 


The following example source file illustrates how the above IMAGE may be 
referenced and displayed. 


ex_image.c 


{mageno=DT_INAMEC master’): 
suitch ((Ckbd=DT_IMAGE( imageno))) /7™ project and accept input from image 7 
{ 
case DTKBESC: printf("escape key hit"): 
break: 


case DTKBPU:  printf("*page up vas hit’): 
break: 


case DTKBPD:  printf£("*page doun uas hit’): 
break: 

default: 
break: 

+} 7* end suitch 7 


INTERNAL d-tree REFERENCE - DTKIMAGE 
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7.11 MAP - Field Mapping 


DESCRIPTION: 

The "MAP" ability provides the means to define “field" mapping to d-tree. By field 
mapping we mean the ability to copy (map) the contents of one field into 
another. Data type conversions are supported as well as special map considera- 
tions (types). 


SYNTAX: 
MAP (reference name) 
source field destination field map type length 
MAP(C codemap) 
“* source field destination field map type length */ 


code custstatus NO_REPLACE 6 
stat ordstatus REPLACE 
amt_calc net_amt DO_CALC a 


e 'reference_name" - The “reference name" must be a unique Identifier 
for each MAP section. There are no prerequisites or dependencies 
upon the MAP ability’s reference_name. 

e "source field" - The "source field" may contain either the symbolic 
name of the field that contains the data to be copled or a reference 
name to a "CALCS" ability definition. 

e "destination field" - The "destination field" Is where the data will be 
copied to. 

e "map type" - The "map type" will define exactly how the mapping 
process is to occur. Valid entries for this field are described below. 

e "length" - The "length" is the number of bytes to be copied. If no length 
is specified the length of the shorter of the "source" or "destination" 
fields is used. 


MAP TYPES 
The following is a description of the valid "map type" entries: 

@ REPLACE - The contents of the "source field" will replace the contents 
of the "destination field". 

e NO_REPLACE - If data exists in the destination, the map is not 
executed and the contents of the destination field remains unchanged. 
(Numeric Fields: Existing data = non-zero ) 

e DO_CALC- The "DO-CALC" map type maps (copies) the result of a 
calculation into the destination field. The source field must contain the 
reference name of the appropriate "CALCS" ability definition. 

Rather than using a symbolic DODA field name in the "source field" 
entry, a reference name identifying a CALCS definition section is used. 
After performing this calculation, the result is used as the source data 
to be used in the MAP. This result is copied into the destination field. 
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RELATED FUNCTIONS: 
e@ DIPMAPIT - Parsing function. 
@ DT _MAPIT- MAP routine. MAP one field into another. 


TYPEDEF: The MAP ability uses the RELATE typedef DTTRELAT. 
eee dt typdf.h at 2 a 


7* Keyword Relationships »*/ 
typedef struct f{ 


UTEXT type: 7* relationship type 7 
TEXT *lptr; 7* pointer to left structure */ 
COUNT licnt: 7* left pointer count */ 
COUNT ltuyp: 7* type of left structure */ 
COUNT Isrt: 7* left structure alt sort */ 
TEXT ¥rptr; 7* pointer to right structure */ 
COUNT rcnt: 7* right pointer count «/ 
COUNT rtyp; 7* type of right structure */ 
COUNT rsrt: 7* right structure alt sort “/ 
+ DTTRELAT: 


EXAMPLE: As you may recall from the tutorial, the MAP ability is also used by 
the VALIDATE edit. When a selection is made from a seperate file, the data may 
be copied back to the data entry field. The following is an example of how the 
MAP is used in conjunction with the VALIDATE edit. Review the tutorial for fur- 
ther illustration of this feature. 


IMAGE( master) {LSTFLD_ADVANCE} {FRSFLD_BACKUP} 
@DATE FairCom 


@CUD 
+Customer Master 


Customer Number: 


Customer Name: 


Customer Address: 
Customer Status: 


Customer Balance: 


FIELD( master) 
7* Symbol Name Input Attribute Output Attribute Input Order 1/0 Maskex/ 
custnum NUMERIC 
custnam ALLWORDCAPS 
custaddress SCROLL 
custstatus ALLCAPS 
custbal PROTECT 


EDITS( master) 


Customer Has Already Been Entered custnum DUPKEY cust_idx 
Invalid Status custstatus VALIDATE cod_idx codemap codescann prefix 


MAP( codemap) 
7* source field destination field length */ 
code custstatus 6 
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The following diagrams show how the map definitions are defined in the 
DTTRELAT structure. 


MAP FIELD Relationship 
™™ right side ™™ | 


jltyp | Iptr |Jlent}{lsrt{™{rtyp [rptr IrcntIirsrt] 


a a ne ee ee 


7“ REPLACE map type m7 
7“ NO_REPLACE map type *7 


“~ 


DTRTFMAP flag 
DTKDDODA 

DODA pointer 
DODA Number 

map number 
DTKDDODA 

DODA pointer 
DODA Number 

map length with 
map type. 


> Jee? een RY Hiee? SMe ae 
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7™* CALC map type us 

7“ here ve relate CALCS to the RELAT representing 
a DTRTFMAP flag 
DTKCALCS 

CALCS pointer 
CALCS Number 
map number 
DTKRELAT 

RELAT pointer 
RELAT Number 
map length uith 
map type. 
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If the type of map is a CALC type then the left side points to the CALCS 
definition otheruise it pints to the DODA definition. 


If the destination field relates to an IMAGE then the IMAGE to FIELD 


RELAT is stored on the right hand side. If the destination field does 
not relate to an IMAGE then the right hand side is a DODA entry. 


rsrt: We add the map length to the map type value and then 
split them back apart in the map function. See map types belou. 


definition in dt_typdf.h 
udefine DTRTFMAP 38 “~™ Relationship contain a field to field map definition */ 


/* MAP types *7 


ndefine DTMAPCAL 11088 /™* CALC map tupe Ms 
ndefine DTMAPRPL 12888 /“™ REPLACE map type M/ 
define DTMAPNRP 13888 7 NO_REPLACE map type */ 


INTERNAL d-tree REFERENCE - DTKMAPIT 
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7.12 MENU - Menu Support 


DESCRIPTION: 
The "MENU" ability provides the definition for managing a variety of menu types. 
Menu presentation and branching is supported by this ability. 


SYNTAX; 

MENU(reference_ name) 

USES _IMAGE(image_reference_ name) 

/* Call Criteria Type of Call Call Value ue 


MENUC 1) 
USES_IMAGEC 1) 
7 ¥ Call Criteria Type of Call Call Value ™/ 
option=1 SYSTEM dtcatlog 
CURSOR=field option=2 EXECL dt_cattd 


option=3 RETURN a 
option=4 CALL demo_4 
option=S CALLMENU menul 


"reference_name" - The "reference_name" must uniquely identify this MENU 
ability definition section. No prerequisites or dependencies are placed upon the 
MENU "reference_name". 


Note: Before proceeding to define the associated optional keywords, let's first 
discuss how this ability works. Menus are processed within your program when 
the related function DT_MENUS is called. DT_ MENUS will first display an 
IMAGE, accept input from the IMAGE and perform the appropriate action (‘type 
of call") based upon the input and/or cursor position specified in the "call 
criteria" . 


"USES_IMAGE" - The "USES_IMAGE" keyword must be present and is used to 
identify the IMAGE to be displayed and accept input. This identification is ac- 
complished via the "image_reference_name". The "USES IMAGE" must be 
present and must 'tie’ to a previously defined "IMAGE" ability. 


"Call Criteria" - The "Call Criteria" defines what circumstances must exist to in- 
itiate execution of its associated call. Within the "call criteria" you may enter two 
different forms of criteria which will define the circumstances. The first type of 
criteria is based upon the value of a field (field =value e.g. select =1). The 
second form of criteria is determined by the field that the cursor was last on 
(cursor =field e.g. cursor=select). These criteria may be used individually or 
together in an "and" logic relationship. When used together, both criteria must 
be true before the appropriate action is taken. Multiple lines of "call criteria" may 
be used in conjunction with a single menu. 
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"Type of Call" - When the call criteria is determined to be true, the type of call is- 
sued will use the given “call value" to perform "call". The "Type of Call" may be 
one (1) of four system keywords. 

@ EXECL - The "EXECL" option will call the program defined in “call 
value" with a "“execlp" call, turning program control over to the "called" 
program and freeing the "caller' from memory. 

@ SYSTEM - The "SYSTEM" option will provoke a "system" call on the 
program name defined in the "call value", allowing control to return to 
the primary program. 

e CALL - The "CALL" option will call the function defined in the "call 
value". This function must be defined in the "user define function table" 
(DTSFUNCT). 

e RETURN - The "RETURN" option will define that the DT MENUS 
function is to return the value defined in the "call value". 

e@ CALLMENU - The "CALLMENU" option will execute another MENU 
identified by the reference name defined in the "call value". The 
DT_MENUS function is called recursively. 


"Call Value" - The "Call Value" may be one of multiple items to be used by the 
“call type". The following table illustrates the required contents of the “call value" 
based upon the value of the "call type" entry: 


Call Type Call Value 

EXECL Valid executable program 

SYSTEM Valid shell command or executable object 

CALL Valid function name(defined in DTSFUNCT table) 
RETURN Return integer return value 

CALLMENU Valid MENU reference name 


RELATED FUNCTIONS: 
e DTPMENU - parsing function 
e@ DT_MENUS - Primary menu function. 
@ DT_MNUCK - Called by the DT_ MENUS function. 


OO 
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‘VPEDEF: 
DTTMENUS 


Ie SL EL Le ee 


dt_tuyupdf.h 


Vat ata tata tatatatatataiotalataiataiotaiaiatatatsistatiaistateieisi tii ttt tt tt tt tt ttt it-t-t-t ttt tt tet tt it Pa 


“™* MENUS definitions */ 


tifdef DTKMENUS 
typedef struct { 
COUNT num; 
COUNT imageno: 
COUNT inputfld: 
COUNT cursfld: 
COUNT comptyp: 
COUNT calltyp: 
TEAT *calltxt: 
TEXT *comptxt: 
+ DTTMENUS: 


tendif 


menu number 7 

image number 7 

input field no ™/ 

last field that cursor was on */ 
compare type */ 

type of menu call */ 

call text */ 

compare input field text */ 


at tatatatalaiatataiatatstataiaialataiaisiataiaiaiaiaiaiaiataiaiaisiaiaisictetst.t.i.t.i.t. ttt 1.11. o4 


EXAMPLES: 


IMAGEC 1) 
@DATE 


FIELDC 1) 
“* Symbol Name 
option 


MENUC 1) 
USES_IMAGEC 1) 


7 Call Criteria 


option=1 
option=Z2 
option=3 
option=4 
option=S 
option=6 
option=7 


Conventional Menu 


{LSTFLD_ADUANCE} 


FairConm OTIME 


d-tree Catalog 


@CUD 


Catalog 

Table Dictionary 
Column Dictionary 
Index Dictionary 
Segnent Dictionary 
Program Dictionary 
Another Menu 


NOU DWN 


Option: 


Input Attribute 
NONE 


Output Attribute Input Order 
NONE 1 


Type of Call Call Value */ 


SYSTEM dtcatlog 
EXECL dt_cattd 
RETURN 3 

CALL menuZ 
EXECL dt_catsd 
RETURN 6 
CALLMENU menul 
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LOTUS STYLE MENU 
IMAGECZ) {INPUT_ADVANCE=CR} 


+ 
+} 

FIELD( 2) 

7* Symbol Name Input Attribute Output Attribute Input Order “/ 
optioni NOCHANGE INPUTRI 1 
optionZ NOCHANGE INPUTRI Z 
option3 NOCHANGE INPUTRI 3 
option4 NOCHANGE INPUTRI 4 

DEFAULTS( 2) 

7% Symbol Name Type of defaults Defaults value */ 
optionl INIT Checks 
option2Z INIT Receipts 
option3 INIT Ad just 
option4 INIT Quit 

MENUC 2) | 

USES_IMAGEC 2) 

7x Call Criteria Type of Call Call Value */ 

CURSOR=option1 RETURN 1 
CURSOR=optionZ RETURN Zz 
CURSOR=option3 RETURN a 
CURSOR=option4 RETURN 4 


POP_UP“PULL DOWN MENU 


IMAGEC3) {INPUT_ADVANCE=CR} {POP_UP} 4{BASE_ROW=4} 
: + 


FIELDC 3) 

7 Symbol Name Input Attribute Output Attribute Input Order aS 
optioni NOCHANGE INPUTRI 1 
optionZ NOCHANGE INPUTRI Z 
option3 NOCHANGE INPUTRI 3 
option4 NOCHANGE INPUTRI 4 

DEFAULTS(C 3) 

7* Symbol Name Type of defaults Defaults value */ 
optioni INIT Modify 
option2 INIT Add 
option3 INIT Delete 
option4 INIT Quit 

MENUC 3) 

USES _IMAGEC3) 

7 Call Criteria Type of Call Call Value »*~/ 


CURSOR=optioni RETURN 1 
CURSOR=optionZ RETURN zZ 
CURSOR=option3 RETURN 3 
CURSOR=option4 RETURN o 


For a full discussion and illustration of applying menus see the TUTORIAL Ses- 
sion 6. 
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7.13 PROMPT - Data Base Access Prompt 


DESCRIPTION: 

The "PROMPT" ability provides a manner to define a method of access into a 
data base. Defining the desired Access to the data base necessitates the follow- 
ing: input from the user, a key or data file number determination; construction. of 
a target" value (TFRMKEY in c-tree) and a "significant length" to use in the ac- 
cess. The DT_PRMPT function provides a means by which the programmer can 
accept data from the user which will be used to initialize four useful work vari- 
ables: key number, scan number, "target" value and the target's "significant 
length". These variables are then ready to use in the access call of choice 

(ie: EQLREC, FRSSET, GTEREC..etc). 


SYNTAX: 
PROMPT (reference_name) 
USES _IMAGE(image_reference_name) 
/* key symbol name scann name fields for target prefix */ 


PROMPT( master) 
USES _IMAGEC prompt) 
“*™ key symbol name scan name fields for target prefix ™/ 


smcustidx master custnum 
smcustidx2 masterZ custnam contact 
NONE master3 option 


"reference_name" - The "reference_name" Is required and must uniquely identify 
this PROMPT definition section. No prerequisites or dependencies are placed 
upon this "reference name". 


Note: Before proceeding to define the associated parameter entries, it Is first 
necessary to have a grasp upon the concepts of how the PROMPT ability 
works. Within your program the function DT_PROMPT is called. Its purpose is to 
do the following tasks: 

* 1. Display an IMAGE. 

a 2. Accept input from the IMAGE. 

@ 3. Analyze the user input with PROMPT definition. 

e 3. Initialize the following associated variables: 


key number - based on user input, proper key number is set. 
scan number - associated scan number is set based in input. 
target value - field concatination and TFRMKEY builds target. 


target significant length - sets sig len for use in c-tree’s SET calls. 


These variables may then be used within a file access routine to retrieve the ap- 
propriate data record. 
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The DT_PRMPT function will first display the referenced IMAGE and accept input 
from the user. It will then evaluate which criteria line matches the data entered 
by the user, and initialize the key and scan number work variables using the as- 
sociated values. Note that multiple fields may be entered in a single "fields for 
target". The same field may be used in more than one criteria line as long as 
each line defines a unique situation. Example: consider three fields on the input 
screen: FIELDA, FIELDB, and FIELDC. You may define the access as follows: 


/* Key symbol Scann Fields for Target */ 
KEY1 SCAN1 FIELDA 
KEY2 SCAN2 FIELDA FIELDB 
KEY3 SCAN3 FIELDB FIELDC 
KEY4 SCAN4 FIELDA FIELDB FIELDC 


If only FIELDA is entered, use KEY1. If FIELDA and FIELDB is entered, use 
KEY2. FIELDB and FIELDC only, must be entered to use KEY3, and if all three 
fields have data the fourth key will be used. This feature provides greater 
flexibility in the selection process. The field(s) entered will be used to build the 
target. If a prefix exists, it is added to that target. Finally, the target’s significant 
length is determined and placed into the corresponding work variable. All four 
work variables are then returned to the calling function. 


NOTE: For further explanation of how the PROMPT ability and the related 


DT_ PROMPT function work, refer to the example at the end of this ability 
description. 


“USES_IMAGE" - The "USES_IMAGE" keyword must be present and is used to 
identify the IMAGE that will be displayed and accept input . This identification is 
accomplished via the “image_reference_name". The "image_reference_name' 
must be present and must reference a previously defined "IMAGE" ability sec- 
tion. The field symbols used in the "fields for target" definition must be found 
within the "IMAGE" referenced. 


The following group of entries establish the values used to initialize the work vari- 
ables based upon the data entered by the user. 


"key symbol name" - The "key symbol name" is required and identifies the key 
symbol used to initialize the key number work variable. This key symbol must be 
a valid index symbol name found in either a c-tree parameter file or incremental 
Structure. A special entry of "NONE" is allowed which results in a key number 
value of 0. This can provide a special indication to the programmer to provoke 
sequential or relative record number access. 
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“scann name" - The "scann name" is required and contains the reference name 
identifying the SCAN number to be used to initialize the scan number work vari- 
able. This allows the programmer the option to provoke a "scan" into the data 
base if the desired access fails. The scan is controlled by the programmer (a 
call to DT_SCANN). DT_PROMPT function only provides the associated scan 
number to use. See SCAN ability. 


“fields for target" - The ‘fields for target" is required and must contain valid 
DODA symbolic name(s) which identify the data field(s) used to determine the 
proper prompt criteria. These fields are then used to form the "target" value. 
These entries must match the symbolic names contained within the "FIELDS" 
ability definition associated with the "IMAGE" ability referenced by the current 
"USES_IMAGE" "image_reference_name" entry. 


"prefix" - The "prefix" entry must be a literal one and will be used to prefix the 
constructed target. This entry is optional and typically will be blank. 


RELATED FUNCTIONS: 
e DIPPRMPT - Parsing function. 
e DT PRMPT- Prompt routine. Provides key number, scan number, 
target, significant length of target for accessing a 
c-tree file. 


TYPEDEF: 
DTTPRMPT 


dt_typdf.h 


MaisisisisisisisisisisisisisisisisisisisisiaisisisiaiaisiaisisiaiaiaalL iLL LL LLL LC LOOT 


“* PROMPT definitions */ 

tifdef DTKPRMPT 

typedef struct { 

COUNT num: 7* prompt number »*/ 
COUNT imageno: “7% image number »*/ 


COUNT scanno: 7* associated scann number */ 
TEXT string; /™ prefix 7 
+} DTTPRMPT: 


tendif 


Malelaisisinisinisisisigisisisisiaisiaiaiainiaiaisisisisisisisiaisia.LLLLLLLLCLLLLL LLC CLT Cr rrr rrr ha 
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EXAMPLE: 
The following script illustrates how the PROMPT ability may appear within a d- 
tree script. 


Customer Master 


Enter Customer Number: 
or 

Enter Customer Name: 
or 

Enter Record Number: 


Press -ESC ESC to EXIT 


FIELD( prompt.) 


7* Symbol Name Input Attribute Output Attribute Input Order 7 
custnum NONE NONE 
custnam NONE NONE 
number NUMERIC NONE 


PROMPT( master) 
USES_IMAGEC prompt > 
7* key symbol name scann name fields for target prefix 7 
smcustidx master custnum 
smcustidx2Z masterZ custnam 
NONE master3 number 


Below is a sample of how the DT_ PROMPT function may appear within your 
program. 


ny_function() 


OUNT scanno; 

EXT target[128]; 

OUNT targsiglen; 

rompt = DT_INAME("prompt"); 


DT_PRMPT(prompt,&keyno,&scanno,target,&targsiglen);. 


A good example of how the DT PRMPT function is used in conjunction with the 
DT_SCANN and DT _EQREC functions is found within the delivered program 
source file DT SCORE.C. 


INTERNAL d-tree REFERENCE - DTKPRMPT 
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7.14 RTREE - Report Front-End 


DESCRIPTION: 
The "RTREE" ability provides a simplified method of building front end user inter- 
faces to r-tree report programs. 


SYNTAX: 
RTREE(reference name) ... see below 


RTREECmy_report) 
USES_IMAGEC my_report) “* report prompt image 7 

USES_SCRIPTC ex_rtree. rts) “™* base r-tree script for report ™*/ 
REPORT_PROGRAM ex_rtree.exe) “* r-tree report Program */ 

RUN_IMAGE(C my_message) “™ screen to display once report starts running*/ 
CALL_TYPE( MEMORY ) “4 report in memory call 7 

CALL_TYPEC EXECL) “7* exec] call */ 

CALL_TYPEC SYSTEM) “7™ system call ™/Z 

CALL_TYPEC SUBMIT) “* submit to backgroup process */ 


“4 r-tree criteria Substitute / 
“* keyuord fields String m7 
SEARCH NONE FILE “ARRAY. ALL 
optionl FILE “‘ARAY. “ USING KEY KEY1 C€ “Coption1}" 
Ooption2 FILE “ARAY. “ USING KEY KEY12 “{Coption2}” J 
optionl 
optionZ2 FILE “‘ARAY. * USING KEY KEY1 C “{option1}” “C{option2}” J 
SELECT NONE ALL 
optionS (Cbalance>@.@@) 
VIRTUAL NONE dev INTZ Z 1 
Option& dev INTZ 2 “Coption6}” 
SORT NONE LEAVE_OUT 
option? NO_MOD “{option7}” 


The "reference_name" must be a unique name identifying this particular RTREE 
ability section. 


In session 6 of the tutorial we discussed step-by-step how to use d-tree to help 
in building an r-tree report. We also discussed how to use the RTREE ability and 
how it relates to the other pieces of r-tree report generation. You may find it 
helpful to review that particular session of the tutorial for further assistance in ap- 
plying this ability. 


The basic purpose of the RTREE ability is to assist in building the related 
specifications for front-end prompts to an r-tree report program. A typical front- 
end prompt for "SEARCH" range criteria (index key range to print , Le. To and 
FROM Customer Number), "SELECT" criteria (i.e. Balance > 0.00), or howa 
report is to be "SORT"ed. The RTREE ability determines how the report is to be 
executed and allows the definition of an IMAGE that can be used as a "status" 
presentation to the user as the report is running. . 
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Before proceeding step-by-step through the logic of how d-tree uses this ability, 
there are a few prerequisites. First, a base r-tree script must already exist. (See 
the r-tree reference manual for specific r-tree information and session 6 of the 
tutorial for information on using d-tree to assist in building this script.) Next, a C 
program, either user-written or generated by the CATALOG, which will use the r- 
tree script to perform the actual report generation, and finally a program that 
provides the user interface. This approach splits the process into two programs. 
A "prompt program" which contains the DT_RTREE function call which displays 
the prompt to the users, performs the proper substitutions to a base r-tree script 
and passes that script to a "report program". The "report program" contains the 
r-tree function call "report". The CATALOG program provides an easy way to 
create both these program's source specs. This "prompt program" and the 
‘DT_RTREE function is where we will focus our attention next. 


The final goal of the DT_RTREE function is to generate an r-tree script, to be 
used by the called report program, which will produce the desired report based 
upon input accepted from the prompt screen. 


To reach this goal DT_RTREE performs the following tasks: 

e Display prompt IMAGE (USES IMAGE). 

e Accept user input. 

@ Merge base r-tree script (USES SCRIPT) with RTREE script 
Substitution definition based upon user input from the prompt screen. 

e Display report "status" presentation to the user while report is running 
(REPORT IMAGE). 

e Call report program (USES PROGRAM) (CALL_TYPE). 


DT_RTREE, the primary RTREE ability function, will first display the IMAGE 
referenced by the USES _IMAGE entry and accept input from the screen. It then 
begins reading the pre-existing base r-tree script, as referenced by the 

USES SCRIPT entry. As it reads the base script it searches for any r-tree 
keywords (SEARCH, SELECT, VIRTUAL and SORT) that were defined within the 
RTREE ability definition in the d-tree script. If one of these keywords are en- 
countered it will then determine, based upon the user input values and the 
criteria from the d-tree script, the proper substitution. Simply stated, we are read- 
ing in one text file, and writing to a new (work) text file. As we do these writes 
we determine if there are any definition lines from the d-tree Script that we want 
to insert (substitute) into the resulting script. The resulting script has a default 
name of DTRTS.BAK. We can better explain this merging process by using an 
example to illustrate. 


eee 
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The first illustration is the prompt screen (USES_IMAGE) to be displayed. 


Customer Report Prompt 
FairCom 


Customer Number: 
From: 
or 
Customer Name: 
From: 
(To report on ALL customers, 


To: 


To: 
leave this section blank. If you 
If 


leave the “To” field blank.) 


wish start at the beginning leave the “From” field blank. 


you want to report to the end, 


(Default: 
«> 8.88) 


Print Accounts: All) 


C=,¢,> + amount) Ci.e.: 


Wiekseda v* 


OUTPUT: (Default: 1, 


Printer nZ; 3 = Screen: 4 = 


Printer #1) 
Disk File) 


Send Output To Device: 
(1 = Printér 81; 2 = 


SORT: Sort CY): _— (Default: No Sort) 


This illustration is the corresponding RTREE ability section from the d-tree script. 


RTREEC cust_report) 
USES_IMAGE(C cust_prompt) 

USES SCRIPTC cust rpt.ris) 
REPORT_PROGRAM( cust_rpt. exe) 
RUN_IMAGEC run_msg) 

CALL, TYPEC SYSTEM) 


report prompt image ™/Z 

base r-tree script for report ™Z 

r-tree report program 7 

screen to display once report starts running 
system call to report progam*/ 


Substitute 7 
String nS 


““ r-tree criteria 
““ keyvord Fields 


FILE 
FILE 
FILE 


“TCUST.. 
UST. 
“GUST, 


SEARCH NONE 

optionl 
optionz2 
optionl 


option2 


DTA 
DTA” 
DTA” 


ALL 
USING 
USING 


“Coptioni}” 
“{optionZ}” J 

FILE “CUST. DTA USING “{Coptioni>” “CoptionZ}” J 

FILE 


FILE 


“CUST. DTA” 
“CUST. DTA” 


USING 
USING 


option3 
option4 


“{Coption3}” 
“CLoption4}” J 


option3 


option4 FILE “CUST. DTA” USING 


“{Coption3}” “Coption4}” J 


SELECT 


VIRTUAL 


SORT 


NONE 
optionS 


NONE 
option6& 


NONE 
option? 
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ALL 
CbalancefoptionS}) 


dev INTZ Z 1 
dev INTZ Z {option6} 


LEAVE_OUT 
NO_MOD “{option7}” 
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In this example we have seven input fields used in our script, option1...option7. 
The four sections found on the input prompt screen, RANGE, SELECT, OUTPUT 
and SORT, relate to the four RTREE keywords SEARCH, SELECT, VIRTUAL and 
SORT, respectively. DT_RTREE will use the data entered by the user on the 
prompt screen to determine the proper entry for each keyword in the resulting r- 
tree script. In our example, DT_RTREE must first determine the proper SEARCH 
entry. If the user does not enter any RANGE information, the first criteria field 
entry in the SEARCH (d-tree script) section is applicable and its associated "sub- 
Stitute string" is entered into the r-tree script. If the user enters data only into the 
first input field, option1, the second line of the SEARCH (d-tree script) section 
would apply and its "substitute string" would be written to the r-tree script. Note 
the syntax used following the "KEY1" entry on that line in the d-tree script. If you 
are familiar with r-tree, the characters used in the syntax of the RTREE ability 
should be very familiar. The left square brace ("[") denotes that the following in- 
formation is the beginning of the lower limit of the range. The right square brace 
("]) denotes that the following information is the end of the upper limit of the 
range. If the user enters data in both RANGE input fields (option1 and option2) 
the fourth entry of the SEARCH (d-tree) section would apply and its correspond- 
ing "substitute string" would be written to the r-tree script. Thus, a lower and 
upper range limit would be established and the corresponding values would be 
substituted. The same logic applies to the Customer Name range fields, option3 
and option4. DT_RTREE will continue down through the script until the first true 
condition is met for each keyword. Therefore, if the user were to enter data in all 
four RANGE fields only the fourth entry would be used. 


Data entered by the user can be inserted into the "substitution string" by placing 
the "field symbol" within {} in the string. 
(ie: SEARCH FILE A USING_KEY KEY1 [ {field symbol 1} {field symbol 2} ] 


Since DT_RTREE will take whatever the user enters and substitute it into the 
proper r-tree script entry, we can allow the user to enter their own SELECT logic 
on the prompt screen. If they elect not to enter anything, it will insert the 
"NONE" "substitute string" into the r-tree script which, in this example, will print 
ALL records within the SEARCH range. 


The next section VIRTUAL provides for the definition of virtual fields. In our ex- 
ample we are using a virtual field to represent the output device which will 
produce our report. If the user leaves this field blank DT RTREE will find a 
match on the "NONE" field entry and write the corresponding "substitute String" , 
to the r-tree script. If a value is entered, this example will insert the value into 
the matching "substitute string" which is written to the r-tree Script. 
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The same type of logic is performed for the SORT keyword section. Note, 
however, one important d-tree keyword (LEAVE OUT) illustrated by the SORT 
section. This keyword will direct DT_RTREE to simply "leave out" the r-tree 
keyword in the resulting script. If the NONE criteria is true, no SORT entry will 
be made. 


Once all substitutions have been made and the script has been built, DT_DTREE 
will display the specified RUN_IMAGE. The following is an example RUN_IMAGE. 


Customer Report 


FairCom 


Your report is now being processed. 


One Moment Please .. 


KEYWORD ENTRIES: 

USES_IMAGE(prompt_image_ reference) - The "USES IMAGE" entry identifies 
the prompt IMAGE definition to be displayed. The "prompt_image_reference" 
must match the reference name of the prompt IMAGE to be displayed. 


USES_SCRIPT(base_script) - The "USES SCRIPT" Identifies the previously 
defined r-tree script used by the function DT_RTREE. The "base _ script" Is the 
filename containing the r-tree script. Traditionally these files use RTS extensions. 


REPORT_PROGRAM (program_name) - The "REPORT_PROGRAM'" identifies 
the program which will be called to generate the final report based upon the 
constructed r-tree script. The "program_name' must be the name of an ex- 
ecutable program which accepts a script name as a parameter and calls the r- 
tree "report" function. (note: the catalog will create this for you). 
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CALL_TYPE(call_keyword) - The "CALL_TYPE" identifies the "type of call" to 
be used by the "prompt program" to pass control to the report process. Only 
one call type is permitted per RTREE section. The “call_ keyword" must be one 
of the following valid CALL_TYPEs. (see dt_rtree.c code) 


e EXECL Execute this report as a separate process with an "execlp" call. 
e SYSTEM Invoke a system call. After execution is complete, control will 
be returned to the calling program. 
e SUBMIT Submit for background processing. Multi-tasking 
environments only. 
e@ MEMORY The r-tree report function is being called directly from the 
prompt program. 
NOTE: The MEMORY CALL TYPE assumes that only one program 
is being used. Report execution is in the same program as the 
prompt program. (see #define in dt_ctree.c for the inclusion of the 
"report" function). 


/* r-tree criteria Substitute */ 
/* keyword fields String *] 


"r-tree keyword" - The "r-tree keyword" is one of the following: 


@ VIRTUAL- — Identifies any necessary virtual field definitions. 
@ SEARCH - Identifies the range of records to process. 

e SELECT - Identifies any selection criteria to be applied. 

e SORT - Identifies any sort specifications. 


See the r-tree reference manual for further information on these keywords 


"criteria fields" - The "criteria fields" relate to what input fields on the prompt 
screen have been entered by the user. Entries must be either the keyword 
"NONE" or valid field symbolic names. (Combinations of field symbolic names 
may be used by placing them directly beneath one another). 


"substitute String" - The "substitute string" is the string of data to be written to 
the r-tree script when a true "criteria fields" condition is met. 


enna eee ec nnnennetnencnnennnnnneeten ne 
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RELATED FUNCTIONS: 
e DIPRTREE - Parsing function. 
e DT RTRE2 - r-tree interface secondary substitution function. 
e DT _RTREE - Primary r-tree front end function. 


TYPEDEF: 
DTTRTREE 


dt_typdf.h 
A tatetatatatotaialatsiataiataiatataiatiatatatatataiatataiaiatateiataiciaiataieatet.taici.i.it.i.t.i.t.t.t.t.i.t.t.1.1.1.1.1-1.1.1-1-1-1-?4 
“7 RTREE interface definitions */ 
tifdef DTKRTREE 
typedef struct { 


COUNT num: 7* rtree definition number */ 

COUNT imageno: “™ image number */ 

COUNT type: 7* interface type */ 

COUNT rtkeyud: 7“ rtree keyword reference number 7 
TERT. Mecript: “7* base r-tree script name 7 

TEXT “string: 7* substitute string 7 

LEAT *program: 7“ program to run */ 

} DTTRTREE: 

teandif 


Vallala alalolelalaialataislalalsialsialaiataialaiolaiataialalaieialeieieict.i.i.i.t.t.i.t1.t.ti.1..1.1.1.1.1.1.1.1.1.1.1.1.1.1.04 


INTERNAL d-tree REFERENCE - DTKRTREE 
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7.15 SCAN - Scan or browse data base 


DESCRIPTION: 
The "SCAN" ability provides for browsing (scanning) through data files. 


SYNTAX: 
SCAN(reference_name) {IMAGE_OUT=?} {IMAGE ROLL=?} {IMAGE_INP =?} 


CIMAGE_OUT=fixed_img {IMAGE_ROL=roll_img} CIMAGE_INP=input_img} 
{USE_SETS=2} 


SCANC master) 


"‘reference_name" - The reference_name is the unique identifier for each SCAN. 
No prerequisites or dependencies apply to this ability reference name. 


This ability is directly related to the d-tree function DT_SCANN. This single func- 
tion performs many very useful tasks. The calling program must pass this func- 
tion the following values: 
@ scan number 
e key number 
e target 
e significant length of the target 
Note that all of these values may be retrieved by the d-tree function 
DT PRMPT. 


DT_SCANN will then perform the following tasks: 

@ project a fixed heading screen (IMAGE OUT) 

e access the data file starting at the point Indicated by the target 

e read records 

@ project records in a ‘rolling’ area on the screen (IMAGE_ROL) 

e control cursor handling capabilities of scrolling up and down through 
the data records 

e handle the editing of data records while displayed In the ‘scrolling’ 
portion of the screen 

e handle data record selection 

@ accept input from either the first or second image(IMAGE_INP) 


All of these tasks are neatly packaged in this single powerful function. 

The DT_SCANN function will return a value greater than zero if no record has 
been selected during the scan process. Otherwise, it will return a value of zero 
meaning a record has been accessed. 
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KEYWORDS: 

IMAGE_OUT=image_ reference name 

The "IMAGE_OUT" keyword identifies the IMAGE to be displayed first. The 
“image_reference_name" must match that of a previously defined IMAGE ability 
section. This IMAGE is normally a fixed header type of display. It normally con- 
tains titles and other constant header information but can also contain 1/O fields, 
such as a Selection input field. 


IMAGE_ROL=image_reference_ name 

The "IMAGE_ROL" keyword identifies the IMAGE which defines the rolling por- 
tion of the display where the records are to be presented. The 
“image_reference_name" must reference the name of a previously defined 
IMAGE ability section. 


IMAGE_INP=image_reference_name 

The "IMAGE_INP" keyword identifies the IMAGE containing any input field(s). 
The "image_reference_name" must match the image reference name of either 
the IMAGE_ROL or IMAGE_INP keyword entries. Thus, the image referenced 
must be a previously defined IMAGE ability section. Only one IMAGE_INP image 
reference name is permitted per SCAN ability section. 


Since you may receive input from either the first or second IMAGE, there are 
two basic approaches to using the SCAN feature: 


Method #1 is to establish the IMAGE_INP as the same IMAGE used by the 
IMAGE_OUT keyword entry. This approach will display a static or fixed header 
screen which should contain a single input field (normally at the bottom of the 
display). Next, display the records using the scrolling or IMAGE ROL portion of 
the screen. Each record should be preceeded by a unique number, the d-tree 
global variable "counter" must be defined on IMAGE ROLL screen .. The user 
may select a record by entering the number corresponding to the desired 
record in the input field on the fixed IMAGE. Reference the TUTORIAL for further 
illustration of this method. 


Method #2 is to indicate that the IMAGE _INP is the same IMAGE as the 
IMAGE_ROL. This is done by using the same image reference names. This will 
then allow the cursor to move freely through the data fields within the scrolling 
portion of the screen. You may edit the data and the disk file will be updated as 
well. This provided the ability to maintain multiple data records on the screen at 
one time. Multi-user aspects such as record locking and multi-user interference 
are not strongly considered at this time in the logic. Please review the 
dt_scann.c file to see the read and write logic if multi-user considerations are 
necessary. 
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USE_SETS{=number} 

The USE_SETS option directs d-tree to use c-tree SET logic (FRSSET, NXTSET). 
In brief, FRSSET logic allows access to a group of qualifying records within a 
data file based upon the target issued and a significant length. For example, if 
the target issued was ‘SMITH’ with length 5, only the records beginning with 
‘SMITH’ in the specified field would qualify for selection. The optional suffix 

"= number’ will direct d-tree to use only that number of bytes for significant 
length of the target. Otherwise, the length of the target is used for the significant 
length. 

For example: Given: target = 'C101' and {USE SETS =2} 

The data file would be accessed at the first occurence of the target C101’, or 
closest point thereto if there was no find on the target. Only records therafter 
containing the value ‘C1’ in the first two positions of the target would be 
retrieved for display to the IMAGE ROL portion of the screen. 


RELATED FUNCTIONS: 
e DIPSCANN - Parsing function 
e DT_SCANN - Primary SCAN function for c-tree data file. 


TYPEDEP: 
DTTSCANN 


dt_typdf.h 
Maleleiaislaielelalaioisleisisleisislsislslaisisalsalsisalsisaisisisilaisislaisiaisiaisisiaiaiaiaiaisisisialaisiaisialaisialaisialald 
7“ SCAN definitions 7 
nifdef DTKSCANN 
typedef struct { 


COUNT num; 7™ scan number 7 

COUNT imgout: “™ header image number 7 
COUNT imgrol: “* rolling image number »*/ 
COUNT imginp: 7* input image number 7 
COUNT useset: “7* use c-—tree FRSSET logic 


“7* values @ = do not use sets 7 


ae -1 = use provided target sig len ™/ 

7M > @ = the sig length to use for sets */ 
COUNT rollines: “7™ number of lines to roll »*/ 
+ DTTSCANN: 
tendif 


Malaiaisisiaisiaioisisiaisisiaisiaiaisisiatalaaisaisicisicicicici.LeLLLLLLLLLLLL LLL LLL LLC LLL LLL oA 
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EXAMPLE: 


@DATE ‘i FairCom @TIME 


Customer Master 
Select Customer Name Number Amount 


Enter Desired Option: __ 
Press ESC ESC to EXIT 


FIELD( heading) 
7* Symbol Name Input Attribute Output Attribute Input Order »*/ 
Option NONE NONE 1 


IMAGECrollpart) {NO_CLS} {LSTFLD_ADVANCE} {FRSFLD_BACKUP} {BASE_ROW=4} 


FIELDC rollpart) 
7* Symbol Name Input Attribute Output Attribute Input Order »*/ 
counter NONE NONE 
custnam NONE NONE 
custnum NONE NONE 
custbal NONE NONE 


SCANC master) {IMAGE_OUT=heading} CIMAGE_ROL=rollpart} {CIMAGE_INP=heading} 


This IMAGE is meet This IMAGE shows | This IMAGE | 


displayed first. data base rcds accepts user 
in a scollable input. 
screen region. 


INTERNAL d-tree REFERENCE - DTKSCANN 
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7.16 SUBFILE - Related groups of records 


DESCRIPTION: | 
The "SUBFILE" ability provides a means to process a related group of records in 
a temporary work space (memory or temporary disk file). 


SYNTAX: 

SUBFILE(reference name) 
SUBFILE(C master) 
SFL_IMAGEC trans) 
SFL_RECORDS( 3Z) 
SFL_LINES( 16) 
SFL_TITLE(transtitle) 


SFL_TARGET 


“* key symbol name fields for target prefix ™/ 
dt_cdseq_id~x td_fil td_version 
SFL_MAP 
/4 parent field child field length */ 
ta fii cna 55% 
td_version —  ed_version 
SFL_SEQ cd_fldseq 
MUSTHAVE 
cd_fldnam 


"reference name" - The "reference name" entry uniquely Identifies this SUBFILE 
ability definition section. No dependencies or requirements are placed upon this 
name. 


The additional d-tree script entries used to define a subfile are best presented 
while discussing the subfile concept. Consider the following illustration: 


DATA 
SOURCE SUBFILE 
LOAD cee 
c-tree Data DISPLAY SCREEN 
File MEMORY 
or OR Scrollable Array 
EDITS of Records 
User Controlled UPDATE TEMPORARY 


DISK 
FILE 


Data 
Source 


Physically, a SUBFILE is either an allocated block of memory or a temporary 
disk file. If an allocated block of memory is used, all subfile records reside in 
memory, and may thus contain only a limited number of records. If you elect to 
use a temporary disk file, you may have a subfile limited by only the amount of 
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available disk space. Processing speed is the advantage of the memory resident 
subfile. Unlimited record capability makes the temporary disk file approach 
more applicable in some cases. 


There are basically four areas which must be addressed when using a subfile: 
e Initializing the subfile. 
e Loading the subfile. 
e Processing the subfile. 
e Updating from the subfile. 


We must initialize an area for our subfile, either memory or disk. This allocated 
area must then be loaded, either from an existing disk file or another source con- 
trolled by user logic. The data residing in the subfile may then be processed, 
typically using screen I/O or another user program defined method. After 
processing is complete, the updated data can then be written back to the 
original disk file or other user program supplied source. Let’s take a closer look 
at each step. | 


Initialize a Subfile 
First, initializing a subfile. To initialize a subfile d-tree must know two things: 
@ Type of Subfile Work Area (memory or disk). 
e Record Size (related c-tree file or user defined group of fields defined 
in the DODA). 


Type of Subfile Work Area 
You may select one of two places to build a subfile: 


e Allocated Memory Block - SFL_RECORDS(number_of record) 
The determination if a subfile is in memory or a temporary disk file is 
made by the SFL_RECORDS entry. If a fixed number of records is 
given (ie: SFL_RECORDS(48) ) the memory subfile is assumed, defined 
to hold that many records (ie: 48 records). d-tree will calculate the 
amount of memory to allocate by multiplying the number of records by 
the maximum record size. The record size is described below. 


e Temporary Disk File - SFL_ RECORDS(1) 
If the SFL_RECORDS entry is a one (1), the subfile is defined as a 
temporary disk file (note: there is no such thing as a subfile that only 
holds one (1) record. The concept of a subfile is to process multiple 
records). 


eee 
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Record Size -The second requirement to initializing a subfile is how the 
size of the records within the subfile will be determined. This may be 
done by either defining the subfile to have a direct association with a c- 
tree file or by defining an association with a group of DODA fields. 


e Association With c-tree File - SFL_TARGET 
d-tree determines the record length via the SFL_TARGET keyword 
entry. Using the key symbol name parameter entered with this 
keyword, d-tree has access to the c-tree file definition. The record 
length found in this c-tree file definition will be the record length used 
for the subfile. This forms a direct association between the subfile and 
the c-tree disk file. The SFL_TARGET keyword will be explained in 
more detail in the subfile processing section. 


e Group of Fields in DODA - SFL_BOUNDARY 
The second option is establishing an association with a group of fields 
defined ina DODA. The SFL_BOUNDARY entry defines the first and 
last fields of a group of fields defined in a DODA. This group of fields 
may be any fields you may want to group together to form a subfile. 
The entries in the DODA must be consecutive, allowing a top and 
bottom boundary to be defined. Using the Identified field definitions 
from the DODA, d-tree is able to determine a subfile record length. 


Load a Subfile 

Once space for our subfile has been allocated and initialized, we must fill it with 
data. If there is no direct association with a c-tree file, the user controls the load 
logic (DT_SFLNW or DT_SFLRW). If there is a direct association with a c-tree 
file, d-tree provides functions to perform the load process. d-tree needs the fol- 
lowing information in order to load the subfile: 


e Source of data. 

e Key for file access (if disk file used). 
e Target for access (if disk file used). 
e Destination of data. 


All of the above requirements are provided via the "SFL_TARGET" keyword. By 
providing the "key_symbolic_name" it not only informs d-tree of the file to ac- 
cess (given a key name, d-tree will know its corresponding data file) but also 
that file’s key for access. The target for access is found in the “fields_for_target" 
entry. 
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The contents of the fields or partial fields, represented by the symbolic names 
entered, will be concatenated together to form the “target" used to access the 
file via the previously mentioned key. If a "prefix" is defined, it will be given an 
address when the "target" is formed. Given the index and the "target" a subfile 
can be loaded with records with c-tree’s FRSSET/NXTSET functions. 


Subfile records are ALWAYS processed as fixed-length records. However, the 
source file definitions may be fixed or variable length. As the subfile is being 
loaded from its defined source, all variable length records are unpacked into the 
subfile. NOTE: The loading of subfiles, as defined in this section, pertain solely 
to subfiles initialized with a direct relationship to a c-tree disk file, using the 
SFL_TARGET keyword. Using the optional method of initializing a subfile with an 
association to a group of fields defined within a DODA, using the SFL_BOUND- 
ARY keyword, requires the user program to be responsible for the load proce- 
dures. | 


Processing a Subfile 

After loading the subfile, we are free to process the subfile’s data. d-tree 
provides functions for processing this related group of records. A few of these 
are: 


Standard Read/Write Processing 


e first - DT FSSFL 
e last - DT_USSFL 
@ next - DT NXSFL 
@ previous - DT PVSFL 
@ read - DT EQSFL 
@ write - DT _ SFLRW 
@ add - DT _SFLNW 


Standard I/O processing may use the d-tree functions but must be maintained 
by the user program. 


Screen I/O Processing 

Screen processing is a user's window to the subfile. As the user edits data on 
the screen, they are editing the actual subfile. The screen I/O processing may 
be controlled from within the d-tree script. For our discussion, we will divide the 
screen processing into two obvious classifications, input and output. First, out- 
put. 

To display the records, an associated IMAGE must be defined. This IMAGE is a 
scrollable region on the screen and is ’tied’ to the subfile by using the 
‘“SFL_IMAGE’ keyword. Static headers may be defined to identify column head- 
ings pertaining to the data displayed in the subfile. This header or title IMAGE is 
identified by the "SFL_TITLE’ keyword. 


—_-— eee 
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One other parameter which must be defined for output is how large of an area 
on the screen should be used to display the subfile, the whole screen or just a 
small window.The width of the subfile display is controlled by the SFL_IMAGE 
but the length is controlled by the 'SFL_LINES’ keyword entry. Note that this 
entry does not include the number of lines required by the header portion of the 
display, SFL_TITLE, only the number of lines to be actually used by the data 
records. This entry must be large enough to contain at least one record and 
should be divisible by the number of lines required by a single record. This num- 
ber should also divide evenly into the SFL_RECORDS entry (assuming the 

SFL RECORDS is not 1). The maximum lines any subfile record can be is the 
screen size (typically 24 lines) . 


Input screen processing is nicely controlled by d-tree. This includes cursor con- 
trols, page up, page down, maintaining input fields, etc. When viewing multiple 
screens of records, you have the ability to control when the subfile image will 
scroll to the next page of records. The SFL_ATTR keyword with the 
NO_ROLL_CR attribute option will inhibit the subfile from scrolling when a car- 
riage return is issued while the cursor is positioned on the last field of the last 
record on the screen. 


Updating From a Subfile 

If the subfile was initialized and loaded from an associated c- tree disk file, d- 
tree provides functions to handle the update procedures. The method of update 
used by d-tree is the 'wash’ method. All original records loaded into the subfile 
are deleted (DT DLSFL) from the original c-tree file and the edited records in 
the subfile are loaded (added DT_ADREC) back into the c-tree disk file. Con- 
sider the following update flow: 


e 1) First all records in the c-tree file that were loaded into the subfile are 
deleted from disk. 

e 2) Read a subfile record. 

e 3) Any data defined to be copied Into (mapped) each subfile record Is 
now copied. The definition of data to be mapped is provided by the 
SFL_MAP keyword. Simply place the "parent" or source field symbol 
name along with the "child" or destination field symbol within the 

SFL MAP section in the d-tree script. 

e 4) The subfile record is checked to see if is "worthy" to be written to 
disk. The definition used to determine this is provided by the 
SFL_MUSTHAVE keyword. A record is "worthy" to be written to disk 
is it passes the "must have" check. Within the SFL_MUSTHAVE 
section define the fields that "must have" data in order for this record 
to be "worthy". If the record passes this check it is written (added_ to 
the c-tree file.) 

e 5) Repeat steps 2 thru 4 for each subfile record. 
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KEYWORDS: 

e SFL_IMAGE(image reference) - The "SFL_IMAGE" keyword identifies 
the associated image by which the subfile records will be displayed. 

e SFL_TITLE(title reference) - The "SFL_TITLE" keyword identifies the 
static header image to be displayed over the subfile records. 

e SFL_RECORDS(number) - The "SFL_RECORDS" keyword sets the 
maximum number of records which will be buffered in the sub- file. An 
entry of ‘1’ designates an unlimited number of sub-file records may 
exist within a disk file. 

e SFL_LINES(number) - The "SFL_LINES" keyword identifies the 
number of lines to be used by the subfile records on the screen. 

@ SFL_ATTR - NO ROLL CR - The "SFL_ATTR" keyword and 
"NO_ROLL_CR" input attribute inhibit screen from paging to the next 
screen full of data when a carriage return is issued while the cursor is 
positioned on the last line of data. The cursor will 'wrap’ to the top of 
the display. 

e SFL_TARGET 
/* key symbol name _ fields for target prefix */ 

The "SFL_TARGET" keyword and related entries are only to be used 
when loading a subfile from a c-tree disk file. This entry is used by 
d-tree to identify the c-tree file to be accessed, the key to the file, the 
record size to be used, the target for access, and any prefix to attatch 
to the target before attempting access. 


key symbol name - The "key symbol name" is the symbolic name of 
the index key of the c-tree disk file to be used to load the subfile. 


fields for target - The ‘fields for target" are symbolic field names, 
which when concatenated will construct the target to be used, via the 
key of the c-tree disk file, to load the the subfile. Multiple symbolic field 
names are allowed. To use only the first n bytes of a field, place the 
number of bytes to be used at the end of the end of its symbolic field 
name surrounded by parentheses. (i.e. cust_name(10) 


prefix - The "prefix" will be placed at the front of the contents of the 
constructed target before attempting to access the data. This must be 
a literal value. 


SFL_BOUNDARY 

/* doda first field | doda last field */ 

The "SFL_BOUNDARY" defines the first and last fields of a group of 
fields within the DODA. This entry is only used when the subfile is to be 
loaded with data from a source other than a c- tree disk file. The fields 
to be used in the DODA must be contiguous. This is used by d-tree to 
determine the record size of the subfile. 
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The "doda first field" is the first field of a group of fields defined in the DODA. 
The "doda last field" is the last field of group of fields defined in the DODA. 


e SFL_MAP 
/* parent field child field length */ 
The "SFL_MAP" option is used to copy data into subfile records just 
before they are updated to disk. For instance, if the master file has a 
field for customer !D and the subfile does too, this allows a change to 
the master field to automatically be updated to the subfile. Parent will 
be in master and child in subfile. 
EXAMPLE: 
The "parent field" is the field in the Master file which will contain the 
information to be copied. 
The "child field" is the field in the subfile which will receive the data. 
The "length" is the length of the data being mapped. If no length is 
specified the shorter of the two field lengths, "parent" or "child", is used. 


e SFL_MUSTHAVE - The "SFL_MUSTHAVE" keyword identifies fields 
which are required to contain data before the record Is written to disk. 
(Note: edits be placed upon these fields at input). 


RELATED FUNCTIONS: 
e DTPSUBEFL - Parsing function. 
e DT _SFCAD - Subfile Child Add Routine. 
e DT _SFCLD - Load child subfile routine. 
e DT SUBFL - Maintain Subfile. 
e DT SFLOT - Subfile Out. Display the Subfile. 
e DT SFHLD - Subfile High Level Load. 
e DT SFLLD - Load Subfile-Low Level. 
e DT_SFHDL - Subfile High Level delete. 
e DT _SFLDL - Subfile low level delete-delete a group of c-tree records. 
e DT _SFHAD - Subfile High level add. 
@ DT _SFLAD - Subfile Low Level Add Routine. 
e DT _SFLRM - Remove temporary subfiles from disk. 
e DT _FSSFL - Get first record in subfile. 
e DT EQSFL - Get record in subfile. 
e DT _LSSFL - Get Last subfile record. 
@ DT _NXSFL - Get next record in subfile. 
e DT _PVSFL - Get previous subfile record. 
e DT _SFLRW - Subfile rewrite. 
e DT_SFLNW - Add a new record to subfile. 
e DT EDSFL - Edit a subfile. 
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TYPEDEF: 
DTTSUBFL 


pecs tty pdf. fh ee ee 


7 OOOO B0CO0CO0 COCO ROOOCP POOL ALLAAH AHO OHH HOH OE OOH 
7“ SUBFL definitions */ 
ifdef DTKSUBFL 


typedef struct { 


TEXT *sptr; 7* sfl memory block */ 

COUNT datno; 7* subfile temp file datno (unlimited subfiles) */ 
TEXT targetC(MAXLEN]: “* target used to load sfl »*/ 

COUNT tarsigln: 7* target sig length */ 

COUNT noofreds; 7* number of records in sfl »*/ 

COUNT currcd:; 7* current sfl record */ 

COUNT currouw; 7* current sfl rou */ 

+ DTTSUBSB; 

typedef struct { 

COUNT num; 7* subfile number 7 

COUNT imageno; 7* image number »*/ 

COUNT title: 7* title image number »*/ 

TEXT “prefix; 7* target prefix */ 

COUNT maxrcds: 7* max number of records for subfile 7 

COUNT sfllines:; 7* total number of display lines for subfile »*/ 


COUNT startdoda: 7% starting doda occurance number 7 


eee 
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Example: 
IMAGECmaster) {LSTFLD_ADVANCE} 
GDATE FairCom @TIME 
File Name: File Description: 
Validation Number: System Name: 
File Type: Extension: Mode: __ Rcd Len: Indexes: 
IMAGECtranstitle) {CLR_LINES=19} €BASE_ROUWU=5}) 
Field Field First Vlen 
Name Type Len Dec Description Field 


IMAGEC trans) {NO_CLS} C(LSTFLE_ADVANCE} {FRSFLD_BACKUP} {CBASE_ROUW=7) 


ee — oe ne ee ne a RR eet 


FIELD(C master) 

“7* Symbol Nane Input Attribute Output Attribute Input Order I/0 Mask »®/ 
td fil ALLCAPS NONE 1 
td_desc SCROLL ALLUORDCAPS NONE 2 
td_version NUMERIC NONE 3 
td_system FRSUORDCAPS NONE 4 
td_type ALLCAPS NONE S 
dxtdsiz NUMERIC NONE 6 
dfilmod NUMERIC NONE 7 
dreclen PROTECT NONE 8 

dnumidx PROTEL NONE 3 


FIELDC trans) 
“* Symbol Name Input Attribute Output Attribute Input Order I/O Mask */ 


cd_fldnam NONE EOL 1 
cd_fldtyp ALLCAPS TABLE_IN TABLE_OUT A 
cd_fldlen NUMERIC NONE 3 
cd_dec NUMERIC NONE 4 
cd_desc NANECAPS NONE S 
cd_vlen ALLCAPS NONE 6 
SUBFILECmaster) 
SFL_IMAGE( trans) 
SFL_RECORDS(C 32) 
SFL_LINESC16) 
SFL_TITLEC transtitie? 
SFL_TARGET 
“74 key symbol name fields for target prefix ™/ 
dt_cdseq_idx td_ fil td_version 
SFL_MAP 
“/™* parent Field child field length */7 
td_fil ed Fil 
td_version cd_version 
SFL_SEQ cd_fldseq 
MUSTHAVE 
cd_fldnam 


Internal d-tree Reference - DTIKSUBFL 
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7.17 TABLES - Alternate Data Representation 


DESCRIPTION: 

The "TABLES" ability establishes a cross-reference between data representation 
on disk and its appearance when displayed on the screen. This ability allows 
coded data from the data base to be presented in "alternate" form to the user. 
This "alternate" form can also be entered by the user and this ability will convert 
it to the “coded" form on disk. | 


SYNTAX: 
TABLES (reference_name) 
disk representation screen representation source field(s) 


TABLES( trans) 

/* disk representation screen representation source field */ 
c cd_fldtyp 
CU cd _fldtyp 
I cd_fldtyp 


IU cd fldtyp 


"reference name" - The "reference name" must be a unique Identifier for this 
TABLE definition section. 

NOTE: Although multiple TABLE sections are allowed, d-tree will consolidate all 
TABLE definition sections into one master table, therefore, the same field can- 
not have more than one alternative representation. 


The following describes what Invokes the TABLE ability and how it works. 
The TABLE ability is directly associated with the TABLE_IN and TABLE_OUT 
input and output attributes defined in the FIELD section: — 


TABLE_IN - When a field has been defined with a TABLE _IN attribute, you are 
indicating that when a value is entered into this field the table should be check- 
ed to attempt to find a "screen representation" for this field that Is equal to the 
value that was just entered. If one is found, the disk representation is then sub- 
stituted into that field’s address. This is very useful in presenting data in a more 
"user friendly" manner while storing a minimum number of bytes (coded data) 
into the data base. 


TABLE_OUT -The TABLE OUT is the opposite of the TABLE _IN and pertains to 
output. If a TABLE OUT attribute is encountered on a specific field when it is 
being displayed, d-tree will search the TABLE for an entry for that specific field 
which has a "disk representation" value equal to the value of the field. If a match 
is found, the corresponding "screen representation" from the TABLE Is dis- 
played. This allows you to take "coded" data from disk and expand it into a 
more "user friendly" representation on the screen. 
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TABLE ENTRY - a single table entry contains the following: 


e "disk representation" - The "disk representation" is the contents of the 
data field as it is to be stored on disk. 

@ ‘screen representation" - The "screen representation" is the contents 
of the data field as it is to be displayed or entered on the screen. 

-@ "source field(s)" - The "source field" is the symbol name(s) 
representing the field(s) which contains an "alternative" definition. 


RELATED FUNCTIONS: 
e DIPTABLE - Parsing function 
e DT _FLDIN - Input a field (Field In). When TABLE-IN attribute is 
considered 
e DT _FLDOT - Display a field (Field Out). When TABLE-OUT is 
considered. 


TYPEDEF: 
DTTTABLE 


dt_typdf.h 
Atitisitititinininisisisiaisisisiaiainisisisisisiniiisisiisaisiaislieisis LCCC rT TTT ee 
/* TABLE interface definitions */ 
sifdef DTKTABLE 


typedef struct { 
COUNT num; 7% table number */ 
COUNT £dodano: 7* doda field number */ 


TEXT *disk; 7“ disk representation of field */ 
TEXT *scrn; “7* screen representation of field */ 
+ DTTTABLE: 


tendif 


Meitititistinisisisisisinisisiainianiaisisisisisiniiisisii isis LLC errr TTT TTT ree 
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Example: 


The following example is taken from the DTCATLOG.DTS script. When using the 


DTCATLOG program and adding a new file, field types are entered as ’C’ for 
char, ‘CU’ for char unsigned, etc. The program, via TABLES, will store a 1 to 


disk to represent the character 'C’ and a value of 2 to represent the characters 


FIELD( trans) 


Type Len Dec Description 


“* Symbol Name Input Attribute 
cd_fldnanm NONE 
cd_fldtyp ALLCAPS TABLE_IN 


cd fldlen 


TABLESC( trans) 
“/™ disk representation 


INTERNAL d-tree REFERENCE - DTKTABLES 


NUMERIC 
NUMERIC 
NAMECAPS 
ALLCAPS 


Output Attribute 


C 
CU 
I 
IU 
L. 
LU 


EOL 


TABLE-OUT 


NONE 
NONE 
NONE 
NONE 


screen representation 


First Vlen 
Field 


Input Order 


cd_fldtyp 
cd_fldtyp 
cd_fldtyp 


cd_fldtyp 
cd_fldtyp 
cd_fldtyp 
cd_fldtyp 


= YP 
cd_fldtyp 
cd_fldtyp 
cd_fldtyp 
cd_fldtyp 


“«/ 


source field ™/ 
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DTPIMAGE. 
DTPKEYBD. 
DTPKEYST. 
DTPMAPIT. 
DTPMENUS. 
DTPPRMPT. 
DTPRTREE. 
DTPSCANN. 
DTPSUBFL. 


d-tree Reference Guide 


DT ADDIT 


NAME 
DT ADDIT- Add one field to another given only DODA symbol names. (doubles 
only) (DT _WDODA.C) 


TYPE 

Data Management 

DECLARATION 

COUNT DT ADDIT(dsymb,ssymb) 

TEXT *dsymb; /* desination symbol */ 
FEAT *ssymb; /* source symbol */ 
DESCRIPTION 


Given two DODA symbolic names, add the value of the second to the first. This 
function uses DT_TDODA to get the addresses pertaining to the symbol names 
and then does the addition. The result is that the value at the destination 
symbols’s address has now been incremented by the value at the source’s ad- 
dress. This function assumes that the symbols being passed are of double type. 
Use this as an example if other types are needed. 


RETURN 

NORMAL RETURN 

Returns a zero if successful. 
ERROR RETURN 

Returns a 1 if error. 


EXAMPLE 
if (OT_ADDIT("F1400a","F703a")) 
printf("Could not add the two values."); 


SEE ALSO 
DT TDODA 


REFERENCE NUMBER - 2B 
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NAME 

DT_ADREC- Add a record to the c-tree data base. (DT CTREE.C) 
TYPE 

File I/O 

DECLARATION 

COUNT DT ADREC(datno) 

COUNT datno; /* data file number to add record to. */ 
DESCRIPTION 


Add a record to a c-tree file. This function uses the d-tree global record buffers 

pointed to by dt_sfp[datno] as the record buffer for the add. This function will 

do the following steps: 

1) Pad the fields in the record buffer with the PADDING character from c-tree. 

2) Execute uniformat logic if defined by c-tree. 

3) Determine the type of file record is being added to: either fixed or variable 
length 

4) If variable length file it will pack the record. 

5) Enable record locking. LKISAM(ENABLE). 

6) Execute c-tree’s add record call. Either ADDREC or ADDVREC. 

7) Free the address record. LKISAM(FREE). 


RETURN 

NORMAL RETURN 

Returns a zero for successful add. 

ERROR RETURN 

Returns the c-tree isam_err value if add has failed. 


EXAMPLE 
if (err =DT_ADREC(datno)) 
printf(target,"Unable to Add record c-tree error = %d'",err); 


REFERENCE NUMBER - 30 


Sn 
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NAME | 

DT_ALDOD- Set the offset values for the field entries in a DODA and return 
either the record length for this group of fields or the number of fields in the 
record. (DT_ALIGN.C) 


TYPE 
DODA Management/Internal Structure Relationships 


DECLARATION 

UCOUNT DT ALDOD(dodaptr,noofflds) 

DATOBJ *dodaptr; /* pointer to first field in record */ 
COUNT noofflds; /* number of fields in record */ 


DESCRIPTION 

Given a starting DODA pointer that is considered to be the first field in a record 
structure, this function will figure out the offsets of each field and place the of- 
fset value in the fhre field in the DATOBJ structure. If a number of fields is 
provided, the record length will be returned. If number of fields is zero, this func- 
tion will return the number of fields it found in the DODA. This function utilizes 
the function DT_STALN to take into consideration the alignment restrictions of 
the hardware. 


RETURN 

If number of fields passed is zero returns number of fields found in the doda 
else if number of fields passed is non-zero. 

Returns the record length of this group of fields. 


EXAMPLE 

rcdien=DT_ ALDOD(dodaptr,nooffields); 
SEE ALSO 

DT STALNQO; /* set alignment array */ 
DT OFSET OQ: /* calc field offsets */ 
DT RCDLN(); /* calc record length */ 


REFERENCE NUMBER - 1C 
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NAME 
_ DT_CALCS- perform defined calculation. (DT _CALCS.C) 


TYPE 
Data Managment 


DECLARATION 

COUNT DT_CALCS (calcptr, ivalue,fvalue) 

DTTCALCS *calcptr; /* pointer to CALCS type definition */ 
LONG *ivalue; /* pointer to LONG result */ 

double *fvalue; /* pointer to floating point result */ 


DESCRIPTION 

When a CALCS ability is parsed from a d-tree script, it is converted from infix to 
postfix form. A pointer to this postfix expression is stored in the CALCS struc- 
ture. DT_EVALU is then called. Using a stack, DT EVALU evaluates the postfix 
expression and performs the appropriate calculations giving the desired result. 


RETURN 
Always returns zero 


EXAMPLE 
DT_CALCS((DTTCALCS *)calcptr,&wlong, &wdouble); 
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DT CLEAR 


NAME 
DT CLEAR- Clear the Screen. (DT_MISCI.C) 


TYPE 
Screen I/O 


DECLARATION 
COUNT DT CLEAR( 


DESCRIPTION 

When DT_KEYBD is called , special control sequences are defined for both 
keyboard and screen. This function outputs to stdout the special sequence of 
characters that were defined in the TERMCAP file to clear the screen. 


RETURN 
Always returns a zero. 


EXAMPLE 
DT_CLEAR(): 


SEE ALSO 
DT KEYBD(); /* Initialize keyboard and Screen definitions from TERMCAP */ 


REFERENCE NUMBER - 83 
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DT CLEOL 


NAME 
DT _CLEOL- Clear Screen to the end of a line. (DT_MISCI.C) 


TYPE 
Screen I/O 


DECLARATION = 
COUNT DT CLEOL() 


DESCRIPTION 

When DT_KEYBBD is called, special control sequences are defined for both 
keyboard and screen. This function outputs to stdout the special sequence of 
characters that were defined in the TERMCAP file to clear the screen to the end 
of a line. 


RETURN 
Always return a zero. 


EXAMPLE 
DT CLEOL(; 


SEE ALSO 
DT_KEYBD(); /* Initialize keyboard and Screen definitions from TERMCAP */ 
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| , DT CLRBK 
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NAME | 

DT_CLRBK- Clear a Block on the screen. (DT MISCI.C) 

TYPE 

Screen I/O 

DECLARATION 

COUNT DT_CLRBK(topcol,toprow,|stcol,lstrow) 

COUNT topcol; /* top left corner of block’s column */ 
COUNT toprow; /* top left corner of block’s row */ 
COUNT Istcol; /* bottom right corner of block’s column */ 
COUNT Istrow; /* bottom right corner of block’s row */ 
DESCRIPTION 


This function's purpose is to clear just a portion of the screen. Only the square 
block defined by the given parameters will be cleared. A block of spaces is writ- 
ten to stdio. 


RETURN 
Always returns a Zero. 


EXAMPLE 
DT_CLRBK(10,12,20,14); /* clear block column 10, row 12 */ 
/* to cloumn 20 row 14 */ 
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DT CMPAR 
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NAME 


DT_CMPAR- Compare elements of the Relate Structure. (DT_RELAT.C) 
TYPE 

Internal Structure Relationships 

DECLARATION 

COUNT DT_CMPAR( cpp1, cpp2 , mode) 

TEXT *cpp1, *cpp2; 

COUNT mode; 

DESCRIPTION 


This function is the compare function called by the DT RSORT routine to deter- 
mine order. 


Valid Modes- (defined in DT_TYPDF.H) 


#define DTQSLTYP 1 /* Sort by left side type. */ 

| #define DTQSLTAC 2 /* Sort by left side type and count. */ 
#define DTQSLTAA 3 /* Sort by left side type and alt sort. */ 
#define DTQSLSRT 4 /* Sort by left side alt sort field. */ 
#define DTQSRTYP 5 /* Sort by right side type. */ 
#define DTQSRTAC 6 /* Sort by right side type and count. */ 
#define DTQSRTAA 7 /* Sort by right side type and alt sort. */ 
#define DTQSRSRT 8 /* Sort by right side alt sort field. */ 
#define DTQSBAAC 9 /* Sort by left side alt and right side cnt */ 


#define DTQSBCAC 10 /* Sort by left side cnt and right side cnt */ 
#define DTQSKYBD 11 /* KEYBD sort-by terminal,key, no of gets */ 
#define DTQSHOOK 12 /* HOOKS sort-by spot (hook location) */ 


RETURN 
Always returns a zero. 


EXAMPLE 
see the routine DT RSORT.C 
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DT COMPI 


NAME 

DT _COMPI- Compile Time Incremental Structures. (DT _COMPI.C) 
TYPE 

Export/Import 

DECLARATION 

COUNT DT COMPI(fp,mode,dothese,totkeys,totsegs) 

Fin shy: /* file pointer for output */ 

COUNT mode; eg 

COUNT dothese; /* which incremental structures to create */ 
COUNT totkeys, totsegs; 

DESCRIPTION 


Output c-tree incremental file definition structure to destination pointed to by 
given file pointer. This function is primarily used to dump the incremental file 
structure definitions from memory to ac source file. This file can then be in- 
cluded into a desired program at compile time. 


Valid mode values: 
0 - do all 
1 - do top and middle 
2 - do middle only 
3 - do middle and bottom 


Valid dothese values: 
0 - do all 
1-doISEGS 
2 -dolIDXS 
3 -do IFILS 


RETURN 
Always returns a zero. 


EXAMPLE 
DT_COMPI(fp,0,0,0,0): 


SEE ALSO 
DT _COMPL.c 
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DT COMPL 


NAME 
DT_COMPL- Create initlized c source code structures for ability definitions. 
(DT COMPL.C) 


TYPE 
Export/Import 


DECLARATION 
COUNT DT COMPL (filename) 
TEAL *filename; /* file name to write definitions */ 


DESCRITPION 

This function creates a source file with the initialized definition of the abilities cur- 
rently defined in memory. It is normally used to create a compiled version of a 
program. Note the following: a d-tree script is parsed using the DT_PARSE func- 
tion. Structures are initialized in memory with the parsed definition. Dumping 
these definitions to disk and including them at compile time would avoid the 
overhead of the parse. This function does this disk dump. 


RETURN 
NORMAL RETURN 
zero returned for successful completion. 


ERROR RETURN 
Symbolic 
Value Constant Explanation 
0x5401 ERR 5401 Could not open disk file. 


EXAMPLE 
if (OT COMPL("MYSOURCE.c’")) 
printf("Could not Write Compile specs\n"); 
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DT CONST 


NAME 

DT_CONST-Output a Constant Value to given screen location (DT CONST.C) 
TYPE 

Screen Interface 

DECLARATION 

COUNT DT CONST(fp, ptr,tlcol,tlrow) 

FILE “ty: /* pointer to destination */ 
DTTCONST ip 8 /* ptr to the def of desired constant */ 
COUNT *tlcol; /* top left base column number */ 
COUNT *tlrow; /* top left base row number */ 
DESCRIPTION 


This function is primarily used to display a constant on the screen by passing 
stdout as the first parameter. An alternative file pointer could be passed. The 
constant definition contains the coordinates that are provided to DT LOCAT 
function for positioning on the screen. If the file pointer is anything but stdout 
then DT_LOCPT is called to do the positioning as if writing to a text file. Option- 
al top left row and column offsets can be passed that will be added to the base 
coordinates of the constant thus allowing constant repositioning via program ~ 
control. 


RETURN 

Always returns a zero. 

EXAMPLE 

DT CONST (fp,rptr-rptr,iptr-topcol, iptr-toprow); 
SEE ALSO - 

DT _IMGMVQ; /* Image output with moving */ 


REFERENCE NUMBER - 20 
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DT CPMEM 


NAME | 
DT_CPMEM- Allocate/Copy Ability Memory Block Definition Space. (DT_UTILY.C) 


TYPE 

Utility 

DECLARATION 

COUNT DT _ CPMEM(oldcnt,newcnt,global,size) 

COUNT *oldcnt; /* number of units in old definition block */ 


COUNT newcnt; /* no of new units to add to definition block */ 
TEXT **global; = /* pointer to old block of memory */ 

COUNT size; /* size of definition units */ 

DESCRIPTION 


This function is used by most parsing routines to allocate the necessary 
memory space to store the parsed definition for an ability. If space has already 
been allocated for the current ability (designated by oldcntO) then a new block 
of memory is allocated that is big enough to contain the existing definition plus 
the space for the new definition. The existing definition is copied to the new 
memory block and the original space is freed. The global pointer that was point- 
ing to the existing definiton is set to point to the new memory block. 


RETURN 

NORMAL RETURN 

A 0 is returned for successful completion. 

ERROR RETURN 

A 1 is returned if the new space could not be allocated. 


EXAMPLE 
if (DT CPMEM(&DTNIMAGE,1, 
(TEXT **) &DTGIMAGE, sizeof(DTTIMAGE)) ) 
printf("Could not allocate space for IMAGE definiton") 
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DT DELET 


NAME 

DT_DELET- Delete Characters from a string. (DT_UTILY.C) 
TYPE 

Utility 

DECLARATION 

COUNT DT DELET(string,pos,no) 

TEAT *string; /* pointer to string */ 

COUNT pos; /* starting position for delete */ 
COUNT no; /* number of characters to delete */ 
DESCRIPTION 


This function is used to delete one or more characters from a string. Given the 
string pointer and the starting position (pos) in the string (0 .. up to .. 
strlen(string)-1 ) this function will remove the given number of characters (no) 
from the string. 


RETURN 

NORMAL RETURN 

returns a zero for successful completion. 
ERROR RETURN 


Symbolic 
Value Constant Explanation 
O0x3701 ERR_3701 Delete position beyond end of string. 
0x3702 ERR_3702 Trying to delete too many characters. 


EXAMPLE 
char ray[64]; 
strcpy(ray,"1234567890'): 


if (DT DELET (ray,1,20)) 
printf("Trying to delete too many chacters'); 


if (}DT_DELET(ray,1,2)) 
printf("string now contains '14567890""): 


REFERENCE NUMBER - 37 


Ae a ee Tage Ta ese ens an ae oe eee ee ee 
d-tree Reference Guide . 8-13 


DT DFALT 


NAME 
DT_DFALT- Execute default logic for the given field and default type. 
(OT DFALT.C) 


TYPE 

Data Management 

DECLARATION 

COUNT DT DFALT(fptr,type,tlcol,tlrow) 

DTTFIELD *fptr; /* pointer to field definition */ 

COUNT type; /* type of default to look for */ 

COUNT tlcol; /* top left base column number for display*/ 
COUNT tlrow; /* top left base row number for display */ 
DESCRIPTION 


This function looks to see if a field has a default definition for the given type. If it 
finds a match, then the default logic is executed. 

Example: If the default key is hit when entering a field (FairCom uses the 
<TAB> key for the default key), this function is called. A pointer is passed to 
the active field and the TAB type of default. This function will look to see if there 
is a TAB definition for this field. If so, it initializes the field with the value from 
the default definition and displays the field. , 

Valid default types: 

TAB - default when default key is hit. 

INIT - default at initialization time. 

DUPTAB - auto dup when auto dup key is hit. 

DUPINIT - auto dup at initialization time. 


RETURN 


NORMAL RETURN 

Number of default definitions found. If no defaults were defined for this field a 
zero is returned, otherwise the number of default definitions for this field is 
returned. 

(NOTE: this is the total number of defaults defined for this field for all default 
types not just for type that was passed.) 


ERROR RETURN 
Symbolic 
Value Constant Explanation 
0x7801 ERR_7801 Memory Allocation error on extract. 
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DT DFALT 


EXAMPLE 
if (kbd = = DTKBAD) 


DT_DFALT (fptr, DTDFTAB, iptr-topcol, iptr-toprow): 
kbd = DTKBCR; 
| /* DEALT */ 


REFERENCE NUMBER - 78 


d-tree Reference Guide 8-15 


DT DFIMG 


NAME 
DT DFIMG- Execute default logic for all fields associated with an image. 
(DT_DFALT.C) 


TYPE 
Data Management 


DECLARATION 
COUNT DT DFIMG(imageno) 
COUNT imageno; /* Image number */ 


DESCRIPTION 

This function will find all the INIT type of defaults for the fields associated with 
the given image. It will then execute the INIT default logic for all fields found. At 
this point in development this function is inefficient. We recommend using the 
DT_DFINI instead of this function to INIT all fields for an image. We provide this 
function at this time as an example of an extract that is based on another ex- 
tract. 


RETURN 
NORMAL RETURN 
Return a zero for successful completion. 
ERROR RETURN VALUES 
Symbolic 
Value Constant Explanation 
0x9201 ERR 9201 Image number passed is not defined. 
0x9202 ERR 9202 Could not allocate memory for extract. 


EXAMPLE 
if (OT_DFIMG(3)) 
printf("Could not Initialize value on this image’); 


REFERENCE NUMBER - 92 
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DT DFINI 


NAME 
DT DFINI- Execute the INIT defaults within the given DEFAULTS definitions. 
(DT_DFINI.C) 


TYPE 
Data Management 


DECLARATION 
COUNT DT DFINI(dfaltno) 
COUNT dfaltno; /* pointer to default definition */ 


DESCRIPTION 

This function looks at all definitions within the given DEFAULTS for all INIT 
types. For all INIT types found, the associated fields will be initialized with the 
value from the default definition. 


RETURN 
NORMAL RETURN 
Returns the number of defaults found. 
(Note: this is the total number of defaults found within the given default defini- 
tion, no just the INIT types.) 
ERROR RETURN 
Symbolic 

Value Constant Explanation 

Ox6D1 ERR 6D1_ Invalid Default Number. 

Ox6D2 ERR 6D2 Memory Allocation error on extract. 
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DT DFINI 


EXAMPLE 

This example’s results: 

1) cou_office will be initialized to "Reno Office’ 

2) Cou_name will NOT be affected. 

3) cou_date will be initialized to the sytem’s date. 


/* d-tree script syntax */ 


DEFAULTS (mydefaults) 

ai Symbol Name Type of defaults Defaults value */ 
cou_Office INIT Reno Office 
cou_name TAB Unknown 


cou_date INIT SYSDATE 


/* c source file */ 
myfunct() 


int mydefaults; 


mydefaults = DT_INAME("mydefaults'); 
DF_DFINI(mydefaults); /* execute initialization */ 
return(0); 

} /* end example function */ 
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DT DLREC 


NAME 
DT DLREC- Delete a record from a c-tree data file. (ODT CTREE.C) 


TYPE 
File I/O 


DECLARATION 
COUNT DT DLREC(datno) 
COUNT datno;/* data file number */ 


DESCRIPTION 

This function will delete the current isam record from a c-tree file. It first deter- 
mines if the file is variable length or not and calls either c-tree’s DELVREC or 
DELREC. 


RETURN 

NORMAL RETURN 

Returns a zero for successful delete. 

ERROR RETURN 

Returns the c-tree DELREC or DELVREC error if delete fails. 


EXAMPLE 
if (err =DT DLREC(datno)) 


sprintf(target,"Unable to delete record c-tree error = %d",err); 
DT DOMSG(target); getchar(); 
} /* end if delete error */ 


SEE ALSO 
c-tree’s DELREC and DELVREC. 
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DT DODBK 


NAME 
DT _DODBK- Check if DODA entry is Blank (or zero). Check to see if the field 
address pointed to by the given DODA entry contains a value. (DT_FIELD.C) 


TYPE 
DODA Management/Internal Structure Relationships 


DECLARATION 
COUNT DT DODBK(fdoda,isvalue,fvalue) 
DATOBJ *fdoda; /* pointer to DATOBJ entry */ 


LONG *jvalue; /* pointer to LONG */ 
double *fvalue; /* pointer to double */ 
DESCRIPTION 


Given a DATOBJ pointer, check to see if the associated field address contains a 
_ value. Alpha fields are check for characters and numeric fields are checked for 
zero. If a value exists and is alpha, the value is pointed to by the doda. If it is a 
long integer, this function returns a pointer to the value as the second 
parameter. Likewise, if the value is floating point, a pointer to the value is 
returned as the third parameter. 


RETURN 
Returns a zero if field has a value. 
Returns a 1 if field is blank or zero. 


EXAMPLE 
if (OT_DODBK(dodaptr,longptr,floatptr)) 
printf("value is zero"); 
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BT DODTS 


NAME 

DT DODTS- Create default d-tree script. (DT DODTS.C) 
TYPE 

Export/Import 

DECLARATION 

COUNT DT DODTS(script,dtstyp, flag) 

TEXT *script: /* Source script to aid creation */ 
COUNT dtstyp; /* type of pgm script to create */ 
COUNT flag; /* where to get field text flag */ 
DESCRIPTION 


This function creates a default d-tree script. It assumes that the there is a DODA 
initialized with the fields to be used for the script. 


RETURN 
NORMAL RETURN 
return O for successful completion. 


ERROR RETURN 
Symbolic 
Value Constant Explanation 
0x8901 ERR 8901 Could not open base script. 
Ox8902 ERR 8902 Could not write temp dtree script. 
0x8903 ERR_8903 Could not open user script. 


EXAMPLE 

/* create d-tree script section */ 

if (OT DODTS(DTDTSSTD,;script)) 
printf(‘Could not Create d-tree script"); 


REFERENCE NUMBER - 89 


d-tree Reference Guide 8-21 


DT DOINT 


NAME 
DT_DOINT- Initialize d-tree record buffers. (DT CTREE.C) 


TYPE 
File I/O 


DECLARATION 
COUNT DT DOINT(datno) 
COUNT datno; 


DESCRIPTION 

This function initializes the record buffers associated with the given data file num- 
ber. d-tree allocates three record buffers for record maintenance. All three buf- 

_ fers are filled with NULLs. 


RETURN 
Always returns a zero 


EXAMPLE 
DT_DOINT(1); /* initializes file number 1 buffers */ 


SEE ALSO 
DT_INBUF(); /* initialized memory buffer */ 
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DT DOMSG 


NAME 
DT DOMSG- Display a message on the screen on the default message line. 
(DT _MISCI.C) 


TYPE 
Screen I/O 


DECLARATION 
COUNT DT DOMSG(msg) 
TEXT *msg; /* pointer to message */ 


DESCRIPTION 

Displays a message on the default message line. The default message line is 
defined in DT_TYPDF.H. 

#define DT _MSGLN 24 /* Error message default line */ 

The message text is centered on the message line. This function is used by d- 
tree to display error messages from the edits functions. 


RETURN 
Always returns a zero. 


EXAMPLE 
if (err =DT ADREC(datno)) 


sprintf(target,"Unable to Add record c-tree error = %d",err); 
DT DOMSG(target); getchar(); 
} /* end if add error */ 
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DT DOPAD | 
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NAME 
DT_DOPAD- Pad fixed length fields in given data file record buffer. 
(DT_CTREE.C) 


TYPE 

File I/O 

DECLARATION 

COUNT DT DOPAD(datno) 

COUNT datno; /* data file number */ 
DESCRIPTION 


This function is used to pad the fixed length fields in a given data file’s record 
buffer with the PADDING character defined in c-tree. This function is normally 
called before a record ADD to ensure key values are consistent. | 


RETURN 
This function always returns a zero. 


EXAMPLE 
DT _DOPAD(1); /* pad fields for file number 1 */ 
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NAME 

DT_DORTS- Create default r-tree script. (DT DORTS.C) 
TYPE 

Export/Import 

DECLARATION 

COUNT DT_DORTS(script,myfile,openmode, flag) 
TEXT *script: /* script name to create */ 


COUNT myfile;/* file number for SEARCH default */ 
COUNT openmoade; /* open file mode */ 
COUNT flag; /* constant text flag */ 


DESCRIPTION 
This function creates a default r-tree script. It scans the relate structure and 
writes an entry into the r-tree script for each FIELD type found. 


RETURN 
NORMAL RETURN 
return 0 for successful completion. 


ERROR RETURN 
Symbolic 
Value Constant Explanation 
0x9001 ERR_9001 Could not write new r-tree script. 
0x9002 ERR_9002 Could not open d-tree script. 
0x9003 ERR_9003 Could not find master screen. 


EXAMPLE 
if (OT _DORTS("MY.RTS",1)) 
printf("Could not create r-tree script"); 
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DT EDATE 
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NAME 
DT_EDATE- Edit Date (DT EDITS.C) 


TYPE 
Data Management 


DECLARATION 

COUNT DT_EDATE(dodaptr,edttyp) 
DATOBJ *dodaptr; /* field to edit */ 
COUNT edttyp; /* type of date edit */ 


DESCRIPTION 

This function validates the specified field as a valid entry of the date type 
passed. Valid date types are: 

DTETDAT1 - DATE edit.-MMDDYY. 

DTETDAT2 - DATE edit.-MMYY. 

DTETDATS - DATE edit.-MMDD. 


Additional date types may be added by the user. (See DT_TYPDF.H for edit type 
#defines and DT_EDITS for source file) 


RETURN 
Any non zero value indicates edit failed. 
A zero value means that the field passed the edit. 


EXAMPLE 
error=DT_EDATE(((DTTFIELD *) (rptr-Iptr))-fdoda, 
((OTTEDITS *)(rptr-rptr))-edttyp); 


SEE ALSO - 
DT _EDITS(); /* primary edit function */ 
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DT EDITS 


NAME 
DT_EDITS- Execute edit logic defined for a certain field or all fields within one 
EDITS section. (DT_EDITS.C) 


TYPE 

Data Management 

DECLARATION 

COUNT DT EDITS (fptr,editno) 

DTTFIELD *fptr; /* field pointer to edit */ 

COUNT editno; /* EDITS number for edit definitions */ 
DESCRIPTION 


This function can be used in two ways: 

1) If a field pointer is passed, execute all edits defined for this field. This mode is 
called upon input of each field. 

2) If an EDITS number is passed, all edits defined in this EDITS section are ex- 
ecuted. This mode is usually called to edit all fields at once, prior to disk update. 
If an error is detected then the error message is displayed via the DT DOMSG 
function and the error id is returned. 


RETURN 
NORMAL RETURN 
If an edit passes then zero is returned, otherwise, if an edit fails, it’s edit Id is 
returned. 
ERROR RETURN 
Symbolic 

Value Constant Explanation 

0x6701 ERR_6701 Memory Allocation error on extract. 
EXAMPLE 


if (ODT_EDITS((DTTFIELD *)O, 1)) 
printf(“Edit for EDITS(1) failed: DO NOT POST DATA’); 


SEE ALSO- 

DT DOMSG(Q; /* display message / 

DT EMAND(); /* MANDATORY edit. */ 
DT EFILLQ; /* MANDATORY fill edit. */ 
DT EDATE(; /* DATE edit. */ 

DT ETABL(); /* TABLE edit. */ 

DT EDUPK(; /* Duplicate key edit. */ 
DT EVALD(); /* VALIDATE edit. */ 

DT ESFLH(; /* Subfile Hash edit. */ 
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NAME 
DT_EDUPK- Duplicate Key Edit (DT EDITS.C) 


TYPE 
Data Management 


DECLARATION 

COUNT DT EDUPK(dodaptr,txtptr) 

DATOBJ *dodaptr; /* Field Pointer */ 

TEXT *txtptr; /* key number for edit */ 


DESCRIPTION 

This function performs c+tree’s TFRMKEY on the record buffer associated with 
the given field pointer, using the key number contained in txtptr. The target from 
TFRMKEY is used to see if an entry already exits in the index for this value. 


RETURN 
A non zero value indicates duplicate key found. 
Zero means field passed edit. 


EXAMPLE 
This edit function is called from DT_EDITS. See DT EDITS.c 


SEE ALSO - 
DT_EDITS(); /* primary edit function */ 


REFERENCE NUMBER - 2F 


ee eeeeEeEeeeeSFSeSeSeSeSeSsSsSsSsSF 


8-28 d-tree Reference Guide 


DT EFILL 


NAME 
DT_EFILL- Mandatory Fill Edit (ODT _EDITS.C) 


TYPE 
Data Management 


DECLARATION 

COUNT DT_EFILL(dodaptr, length) 
DATOBJ *dodaptr;  /* pointer to field */ 
COUNT length; /* length of field */ 


DESCRIPTION 
This function is called to ensure every character in the given field has a charac- 
ter. 


RETURN 
Returns a value is field does not have a character in every byte. 
Returns a zero is all bytes have character. 


EXAMPLE 
This edit function is called from DT_EDITS. See DT_EDITS.c 


SEE ALSO - 
DT _EDITS(); /* primary edit function */ 
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DT EMAND 


NAME 
DT _EMAND- Mandatory Field Edit (DT EDITS.C) 


TYPE 
Data Management 


DECLARATION 
COUNT — DT_EMAND(dodaptr) 
DATOBJ *dodaptr; /* field pointer */ 


DESCRIPTION 
This function checks to ensure that data has been entered into the given field. 


RETURN 
Returns a value if field does not have data. 
Returns a zero if field has data. 


EXAMPLE 
This edit function is called from DT EDITS. See DT _EDITS.C 


SEE ALSO - 
DT EDITS(); /* primary edit function */ 
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DT EQREC 


NAME 
DT EQREC- Get a data record with key value equal to target value. 
(DT CTREE.C) 


TYPE 

File I/O 

DECLARATION 

COUNT DT EQREC(keyno,target) 

COUNT keyno; /* key number for get */ 
TEAY *target; /* target to use for get */ 
DESCRIPTION 


This function performs the following steps: 

a) c-tree’s EQLREC to get the record. if error on EQLREC return error. 

b) Determines if the file is variable length or not. if variable length it then un- 

packs 
the record into the maintenance buffer otherwise it simply copies the read 
record into the maintenance buffer. 

c) if UNIFRMAT is defined, the uniformat logic is executed. 

d) DT_UNPAD is called to unpack fixed length fields. 


RETURN 

NORMAL RETURN 

Returns a zero for successful get. 
ERROR RETURN 

Returns the c-tree EQLREC error if failed. 


EXAMPLE 
if ((DT EQREC(keyno,target))) 
printf("Got a Hit"); 
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NAME 
DT_ETABL- Table Edit Function. Ensure that field value is in a given TABLE of 
values. (DT _EDITS.C 


TYPE 
Data Management 


DECLARATION 

COUNT DT_ETABL(dodaptr,txtptr) 

DATOBJ *dodaptr; /* field to check */ 
TEXT *txtptr; /* list of table entries */ 


DESCRIPTION 

This function scans the list of table elements to ensure that the value of the 
given field is contained in the table. A good example of a table edit is a Y/N 
validation where you only want the user to be able to key a Y oraN.This edit 
function is called from DT_EDITS. See DT EDITS.C 


RETURN 

A nonzero value is returned if field’s value is not found in the table. 
A zero is returned if the value is in the table. 

EXAMPLE 

/* d-tree script */ 

EDITS (master) 

Must Enter a Y or aN cou_cod TABLE Y N 


SEE ALSO - 
DT _EDITS(); /* primary edit function */ 
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DT EVALD 
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NAME 
DT_EVALD- Validation edit. Edit the value of a field as key to another file. 
(DT_EDITS.C) 


TYPE 

Data Management 

DECLARATION 

COUNT DT EVALD (fptr,txtptr) 

DITFIELD ‘*fptr; /* field to edit */ 

TEXT *txtptr; /* validation definition string */ 
DESCRIPTION 


This function validates the given field as a key value in the given key. This func- 
tion is used to edit input such as customer number or account number, or any 
value that can be edited against a unique key. (Customer master Customer num- 
ber key or Account master account key). A SCANN may be defined to allow a 
lookup into the associated file. A MAPIT may be defined if a select was done on 
the scann to map data back to the record being maintained. This edit function is 
called from DT_EDITS. See DT EDITS.C 


RETURN 


NORMAL RETURN 
Returns a zero if a match Is found. 


ERROR RETURN 
Returns a non-zero value if no index match Is found. 


EXAMPLE 

EDITS(master) 

Invalid Code cou_cod VALIDATE ex2idx cmap cscann prefix 
MIM FO VA IAI vo cresiveosusactateenctnccs 

ROR SN cs hecelaie njie edi cch ested . 

Po AOE as esas fecraiclscg ined eet eee sf 

Poe FN to UNE aotre wes oa eoriee  caeeueastaeenetee evades sie 


SEE ALSO - 

DT EDITSQ; /* primary edit function */ 
DT MAPIT(); /* Map data */ 

DT SCANNQ; /* Scann Data file */ 


REFERENCE NUMBER - 3C 
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NAME 
DT EVALU- Evaluate a postfix expression. (DT EVALU.C) 


Note: This function will be supported in commercial version. Not running in beta 
version. 


TYPE 

Data Management 

DECLARATION 

COUNT DT EVALU(in,ivalue,fvalue) 

TEXT *in; /* expression pointer */ 
LONG *ivalue; /* ptr to integer value */ 
double *fvalue; /* ptr to floating pt value */ 
DESCRIPTION 


Using a stack, DT_EVALU evaluates the postfix expression and performs the ap- 
propriate calculations giving the desired result. It is used by the DT _CALCS to 
perform the calculations defined in the d-tree script. 


RETURN 
NORMAL RETURN 
Returns zero if calculation was successful. 


ERROR RETURN 
Returns 1 if error occurred. 


EXAMPLE 
if (OT EVALU(string)) 

printf("unable to evaluate expression’): 
SEE ALSO 


DT CALCS(); /* perform defined calculation */ 
DT_PSTFX(); /* convert a infix expression to postfix */ 


REFERENCE NUMBER - 6B 
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NAME 

_ DT_FLDIN- Control input for given field (DT_FIELD.C) 
TYPE 
Screen Interface 
DECLARATION 
COUNT DT FLDIN(ptr,tlcol,tlrow) 
DITFIELD — *pir: /* field to input */ 
COUNT tlcol: /* top left base column number */ 
COUNT tlrow; /* top left base row number */ 
DESCRIPTION 


To manage input for a specified field. This function will accept input for a given 
field, taking into account attributes, screen location, and field type. 


RETURN 
NORMAL RETURN 
Returns last key hit during maintenance. 


ERROR RETURN 
Symbolic 
Value Constant Explanation 
0x2501 ERR_2501 Input Longer than max field length DT_FLDLN. (see 


DT_TYPDF.H) 
0x0031 DTKBCR Specified field is protected. 
EXAMPLE 
/* INPUT */ 
if ( (kbd = DT_FLDIN(fptr, iptr-topcol,iptr-toprow)) = = DTKBESC) 
break; 
SEE ALSO - 
DT FLDTX(; /* convert text to field */ 
DT INPUT(); /* input function */ 
OT PLDOTO: /* field out */ 
DT LOCAT(); /* screen locate */ 
DT SCSEQQ; /* screen special sequence */ 
DT_INBUF(); /* initilize buffer to nulls */ 


REFERENCE NUMBER - 25 


ea IO a PA Se oT PR ae Se ee ea ee ne ee a eae ae ae 
d-tree Reference Guide 8-35 


DT FLDLO 
ne teeeenseateeheeinententesensnn steerer essinersceemererneeneteere eens 


NAME 

DT_FLDLO- Low level field output routine (DT _FIELD.C) 
TYPE 

Screen Interface 

DECLARATION 

COUNT DT _FLDLO(fp,ptr,Istno,spcatr) 

FILE “10: /* file pointer for output */ 
DITFIELD *ptr; /* field pointer */ 

COUNT *lstno; /* number of characters output */ 
COUNT spcatr; /* table number to do lookup */ 
DESCRIPTION 


This function outputs a field to the given file pointer (stdout). It is called from 
the DT_FLDOT function to output a field’s contents to the screen. 


RETURN 

If there is no data in the field then a 1 is returned. 

If field contains data then a 0 is returned. 

If field is alpha then the number of characters that were output isreturned in 
Istno. 


EXAMPLE 
blank = DT_FLDLO(stdout,ptr,&x,spcatr); 


SEE ALSO - 
DT_FLDOT(); /* output a field */ 


REFERENCE NUMBER - 7A 
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NAME 
DT_FLDNM- Validate a token as a valid field symbol (DT_FIELD.C) 


TYPE 
Table Validation 


DECLARATION 
DTTFIELD 9 *DT FLDNM(token) 
TEAL *token; /* token to validate */ 


DESCRIPTION 

This function validates a token as a valid FIELD symbol name in the DODA. If a 
match is found then a pointer to the FIELD definition is returned. If no match is 
found a zero is returned. 


RETURN 

NORMAL RETURN 

pointer of DI TFIELD type to field found. 
ERROR RETURN 

O for no such field. 


EXAMPLE 
if (DT FLDNM("name’)) 
printf("Not a valid field symbol’); 


REFERENCE NUMBER - 70 
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NAME 

DT FLDOT- Output the contents of a field (DT FIELD.C) 
TYPE 

Screen Interface 

DECLARATION 

COUNT DT _FLDOT(fp, ptr,ticol,tlrow) 

rie “ip; /* file for output */ 

DTTFIELD *ptr; /* field pointer to output */ 
COUNT tlcol:; /* top left base column number */ 
COUNT tlrow; /* top left base row number */ 
DESCRIPTION 

This function is used to display the contents of the field. If the field is blank or 
zero, then underscores (" ") will be displayed. 
RETURN | 

Always returns a zero. 

EXAMPLE 


DT FLDOT(stdio,fldptr,iptr-topcol,iptr-toprow); 
REFERENCE NUMBER - 21 
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NAME 
DT FRAME- Draw a frame on the screen. (DT_MISCI.C) 


TYPE 
Screen I/O 


DECLARATION 

COUNT DT FRAME (fp,tp,tx,ty, bx, by) 

FILE 8 /* file pointer for output */ 

TEXT *tp; /* pointer to text to be included at top line */ 
COUNT tx,ty,bx,by; /*top left col,row; bottom right col,row*/ 


DESCRIPTION 
Draw a frame to the given file pointer(stdout). 


RETURN 
always returns a zero. 


EXAMPLE 
DT_FRAME(01,01,23,23); 


REFERENCE NUMBER - 4C 
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NAME 
DT FREEE- Free Ability Memory Blocks. (DT FREEE.C) 


TYPE 
DODA Management/Internal Structure Relationships 


DECLARATION 
COUNT DT _FREEE() 


DESCRIPTION 

_ This function will free the allocated memory for d-tree abilities that where allo- 
cated from parsing routines or that came from the Ability dictionary. Primarily 
used in catalog master program. 


RETURN 
Always returns a zero. 


EXAMPLE 
DT _FREEE(): 


REFERENCE NUMBER - 2A 
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NAME 

DT FSREC- d-tree get first record. Get the first record in a file. (OT_CTREE.C) 
TYPE 

File 1/O 

DECLARATION 

COUNT DT FSREC(filno) 

COUNT filno; /* data or index file number */ 

DESCRIPTION 


This function performs the following steps. 
a) calls c-tree’s FRSREC to get the first record. if error on FRSREC, return error. 
b) determines if the file is variable length or not. If variable length, it then un- 
packs 
the record into the maintenance buffer otherwise it simply copies the read 
record into the maintenance buffer. 
c) if UNIFRMAT is defined, the uniformat logic is executed. 
d) DT_UNPAD is called to unpack fixed length fields. 


RETURN 

NORMAL RETURN 

Returns a zero for successful get. 
ERROR RETURN 

Returns the c-tree FRSREC error if failed. 


EXAMPLE 
if (}(DT_FSREC(keyno))) 
printf("Got first record in key order’); 


REFERENCE NUMBER - 99 
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NAME 

DT_FUNCT- Validate a token as a valid user defined function. (DT FUNCT.C) 
TYPE 

Table Validation 

DECLARATION 

DT_FPTR DT FUNCT(token) 

TEXT *token; /* token to validate */ 


DESCRIPTION 
This function is used to validate a token as a user defined function in the struc- 
ture dt_user. If a token is the name of a user defined function, a pointer to that 


function is returned. 
FOR AEEAENE ER LEEEERELARAEESCERA EEA ERR EEE | 


/* Valid User defined special functions */ 
DTTFUNCT dt_user[{] = { 
{ "My_Function" , myfunc }, 
{'"", DT_NULFP }  /* terminaton Indicator */ 


leiaietshisietahietetadaaiaceeeeee 
RETURN 
Either a Zero for no match or a pointer to the associated function. 


EXAMPLE 
thefunction() 


DT_FPTR funcptr; 


/* USER FUNCTION */ 
funcptr =DT_FUNCT("My Function’): 
if (funcptr! = DT_NULFP) 

(*funcptr)(); /* call function */ 


return(0); 
} /* end sample function */ 


REFERENCE NUMBER - 69 
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NAME 

DT _GENRL- Validate Token in a General Table. (DT _GENRL.C) 
TYPE 

Table Validation 

DECLARATION 

DTTGENRL *DT_GENRL(base,token,addit) 

DTTGENRL *base; /* base address of table */ 

TEXT *token; /* token to validate */ 

COUNT addit; /* add to table if not in table flag */ 
DESCRIPTION 


This function is used to do a lookup into tables defined as DTTGENRL d-tree 
uses this lookup capability for a variety of validation tables.Note typdef 
DTTGENRL: 

/* GENERAL valid token structure typedef */ 

typedef struct { 


TEXT *string; /* ptr to string for token */ 
COUNT refnum; = /* reference number */ 
COUNT type; /* reference type */ 

} DTTGENRL; 


RETURN 
NORMAL RETURN 
Returns the pointer to the table if a match was found. 
ERROR RETURN 
Returns a zero if no match was found. 
Symbolic 
Value Constant Explanation 
0x1801 ERR_1801 DT GENRL called with invalid table. 
0x1802 ERR 1802 DT _GENRL could not allocate space for symbolic 
names. 
0x1803 ERR_1803 DT _GENRL could not allocate space for symbolic 
name text. 
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EXAMPLE 

haa a na al ate 
/* Valid EDITS types symbols */ 

DTTGENRL dt_genedt[] = { 


{"MANDATORY",DTETMAND }, /* mandatory entry */ 
{"MAND_FILL",DTETFILL }, /* mandatory fill */ 
{"DATE_MMDDYY",DTETDAT1 }, /* date edit-MMDDYY */ 
{"DATE_MMYY",DTETDAT2 }, /* date edit-MMYY */ 
{"DATE_MMDD*, DTETDATS }, /* date edit-MMDD */ 
{"TABLE",DTETTABL }, /* validate against a table */ 
{"DUPKEY",DTETDUPK }, /* check for duplicate keys */ 
{"VALIDATE",DTETVALD }, /* validate against key */ 
{"",-1} /* terminaton indicator */ 


aa ca caer liad Sd 
mytest() — 
{ 

DTTGENRL *gptr; 


if ((gptr =DT_GENRL(dt_genedt,"DUPKEY",0))) 
printf(“reference number = %d\n",gptr-refnum): 


j 
REFERENCE NUMBER - 18 


eee 
8-44 d-tree Reference Guide 


DT HELPP 


NAME 

DT HELPP- execute help function. (DT _HELPP.C) 
TYPE 

Screen Interface 

DECLARATION 

COUNT DT HELPP (ptr,type) 

TEXT *potr; /* pointer to entity for help */ 
COUNT type; /* type of help */ 
DESCRIPTION 


This function is used to display help text for the given ability entry. It will either 
display the help text defined in the d-tree script or it will access the help text file 
with the defined token to access the help. Help is either displayed on the mes- 
sage line or in a subfile display area, depending upon the d-tree script definition. 


RETURN 
NORMAL RETURN 
Returns zero for successful completion 
ERROR RETURN 
Symbolic 
Value Constant Explanation 
Ox851 ERR 851 Could not initialize help text subfile. 
Ox852 ERR 852 = Subfile defined for help text not found. 


EXAMPLE 
see DT_IMGIN in DT_IMAGE.c 
if (kbd = =DTKBHELP) /* help text */ 


DT HELPP( (TEXT *)fptr, DTKFIELD); 
error=1; 
continue; 


} 
REFERENCE NUMBER - 85 


d-tree Reference Guide 8-45 


DT IFILS 


NAME 
DT_IFILS- Open/Create Incremental Files (DT_IFILS.C) 


TYPE 
File 1/O 


DECLARATION 

COUNT DT_IFILS(bufs,extra,sect) 

COUNT bufs; /* number of index file buffers */ 

COUNT extra; /* number of extra files not opened by DT_IFILS*/ 
COUNT sect; /* number of node sectors */ 


DESCRIPTION 

This function will first count all data file and index files defined in the incremental 
structures in order to execute c-tree’s INTISAM. It will then Open (or Create if 
file not found) each file defined using c-tree’s OPNIFIL (or CREIFIL). If a file is 
found to be corrupt at open, automatic rebuilding of the file will be executed if 
the #define DTRBLIFIL is set in DT_DEFIN.H 


RETURN 

NORMAL RETURN 

Returns a zero for successful completion. 

ERROR RETURN 

If function fails, returns c-tree’s error from INTISAM, OPNIFIL or CREIFIL 


EXAMPLE 
if (err=DT_IFILS(10,0,4)) 
printf("\nError Occured During Open IFIL = %d\n",err); 


REFERENCE NUMBER - 81 
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NAME 
DT_IMAGE - Display and Input from an Image (DT_IMAGE.C) 


TYPE 
Screen Interface 


DECLARATION 
COUNT DT_IMAGE(imageno) 
COUNT imageno; /* image number */ 


DESCRIPTION 
This function will display the specified IMAGE by calling the DT_IMGOT function. 
It then calls the DT_IMGIN function to accept input for variable fields on the 
IMAGE. 
RETURN 
NORMAL RETURNS 
This function returns that last key detected from the keyboard. 
ERROR RETURNS 
via IMGOT: 
Symbolic 

Value Constant Explanation 

0x1901 ERR 1901 invalid image number. 

0x1902 ERR 1902 image has no fields. 

0x1903 ERR_1903 could not open print file. 

0x1904 ERR 1904 can’t Use TEMPP type already in use. 

0x1905 ERR_1905 can't allocate TEMPP typespace for print screen. 


via IMGIN: 
Symbolic 
Value Constant Explanation 
0x2601 ERR 2601 Invalid image number. 
Ox2602 ERR 2602 image has no fields. 
EXAMPLE 
if (DT_IMAGE(menu)) = =DTKBESC) 
printf("Escape Was Hit"); 


REFERENCE NUMBER - 27 
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NAME - 

DT_IMGAL - Display and Input a group of IMAGES (DT_IMAGE.C) 
TYPE - 

Screen Interface 

DECLARATION - 

COUNT DT_IMGAL(imageno,begimg,endimg) 

COUNT imageno; /* starting image number */ 
COUNT begimg; /* lowest image number */ 
COUNT endimg; /* highest image number */ 


DESCRIPTION - 

This function can be called for your c program to display and input more than 
one image at a time. The first image to be displayed is passed to this function 
by imageno. This function assumes that the images to be displayed are num- 
bered sequentially. As the user pages up and down the previous or next image 
will be displayed. The beginning and ending set the upper and lower bounds 
respectively for the image numbers. Note that this function is simply a loop set- 
ting imageno and calling DT_IMAGE(). 


RETURN 
Returns the last keystroke from the keyboard. 


EXAMPLE 
if ((DT_IMGAL(1,1,10)) = =DTKBESC) /* maintain 10 screens */ 
printf(Escape Hit"); 


REFERENCE NUMBER - 28 
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NAME 

DT_IMGIN - Input an Image (DT_IMAGE.C) 

TYPE 

Screen Interface 

DECLARATION 

COUNT DT_IMGIN(imageno,curfld,curptr) 
COUNT imageno; _/* image number */ 
COUNT *curfld; /* current field number */ 


DTTFIELD **curptr; /* current field pointer */ 


DESCRIPTION 

This function manages the input of variable fields pertaining to an IMAGE using 
the relate structure to access field definitions related to this IMAGE. For each re- 
lated field found, a DT_FLDIN (field in) function call is made. The field input 
order is controlled by this function, responding to input keys ( UP, DOWN, etc.) 
Based on the last keystroke entered, other special functions are also called from 
this function; such as: 

DT DFALT  - if default key was hit, execute default logic. 

DT HELPP - execute help function if help key was hit. 

DT EDITS _ - if not special function key was hit, edit the field. 

DT IMGOT_ - Image out is called w/output redirected if the print screen key hit. 


RETURN 
NORMAL RETURN 
Returns the last keystroke hit from keyboard. 
ERROR RETURN 
Symbolic | 
Value Constant Explanaton 
0x2601 ERR 2601 DT_IMGI-invalid image number. 


0x2602 ERR_2602 DT_IMG!.. image has no fields. 
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EXAMPLE 

if ( (keystroke = DT_IMGIN(start,&kbd,&notused)) = = DTKBESC) 
return(-1); 

switch (keystroke) 


case DTKBUP: doifup(); /* up key */ 
break; 
case DTKBHM: doifhome(); /* home key */ 
break; 
} /* end switch */ 
SEE ALSO - 


DT HELPP - help function. 
DT_IMGOT - output an IMAGE. 
DT _DFALT - execute default logic. 
DT_FLDIN - input a field. 
DT_EDITS - edit a field. 


REFERENCE NUMBER - 26 
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NAME 
DT_IMGLG - re-display IMAGE’s from the image log (DT_IMAGE.C) 


TYPE 
Screen Interface 


DECLARATION 
COUNT DT IMGLG (level); 
COUNT level; /* log level to display */ 


DESCRIPTION 

This function is used to re-display an image that has been previously written to 
the screen. When the DT_IMGOT (image out) function is called, it is optionally 
logged in the IMAGE LOG. When another screen is written it may overlay the 
current screen. The DT_IMGLG function is used to re-display the IMAGE that 
was overlayed. The image log is a two dimensional array. A clear screen will 
provoke a new level in the log. The level number parameter indicates which 
level to display. 


RETURN 
Always returns a Zero. 


EXAMPLE 
if (Scroverlay) 
DT IMGLG(1); /* redisplay level 1 */ 


SEE ALSO - 
DT_IMGIN - IMAGE In function. 


REFERENCE NUMBER - 1A 
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NAME oes 
DT_IMGMV - Display/Input an Image allowing negag 
will move to the new coordinates. (DT_IMAGE.C) 473 
TYPE 

Screen Interface 


DECLARATION § 
a 


en coordinates. Screen 


COUNT DT_IMGMV(imageno) 
COUNT imageno;  /* image number */ 


DESCRIPTION ; 

This function is the same as the DT_IMAGE function except using the function 
keys F1 thru F4 causes the screen to change it’s base coordinates and be re-dis- 
played. This causes the IMAGE to move around the screen under control of the 
user. 


RETURN 
NORMAL RETURN 
Returns the last keystoke from the keyboard. 
ERROR RETURN 
Symbolic 
Value Constant Explanation 
0x4701 ERR_4701 invalid image number. 


via IMGOT: 
Symbolic 
Value Constant Explanation 


0x1901 ERR_1901 invalid image number. 

0x1902 ERR_1902 image has no fields. 

0x1903 ERR_1903 could not open print file. 

0x1904 ERR_1904 tried to Use TEMPP type that is already in use. 
0x1905 ERR_1905 could not allocate TEMPP type space for print screen. 


via IMGIN: 
Symbolic 
Value Constant Explanation 


0x2601 ERR 2601 invalid image number. 
Ox2602 ERR 2602 image has no fields. 


EXAMPLE 
if ((OT_IMGMV(menu)) = = DTKBESC) 
printf("Escape Hit"); 
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SEE ALSO - 
DT_IMAGE - Output/Input an Image. 


REFERENCE NUMBER - 47 
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NAME 

DT_IMGOT- Ouput an IMAGE (DT_IMAGE.C) 

TYPE 

screen Interface 

DECLARATION 

COUNT DT_IMGOT(imageno,mode,special,speccnt) 
COUNT imageno; /* image number */ 

COUNT mode; /* display mode */ 

COUNT special; /* image logging type */ 
COUNT speccnt; _//* special image logging parameter */ 
DESCRIPTION 


This function is used to display an image to the screen. It accesses all variable 
and constant fields related to the IMAGE via the relate structure. As it finds a re- 
lated field, it either does a DT_CONST (display constant field) or a DT FLDOT 
(variable field out) depending on the variable type. 

IMAGE display modes: 

DTIMGALL - display both constant and variables. 

DTIMGCON - display constants only. 

DTIMGVAR - display variables only. 

DTIMGPWP - print screen (write & print). 

DTIMGPWO - print screen (write only). 

DTIMGPAP - print screen (append and print). 

DTIMGPAO - print screen (append only). 

IMAGE logging types: 

DTIMGREG - nothing special for image out. 

DTIMGLOG - displaying from log-do not log. 

DTIMGSFL - image being displayed is subfile. 

DTIMGNOL - No Log-do not log image. 

Special Image Logging Parameter: 

Used for additional information needed to re-display the image from the image 
log. Example: when a subfile is displayed, the special parameter is the subfile 
number. 
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RETURN 
NORMAL RETURN | 
Returns a zero for successful completion. 
ERROR RETURN 
Symbolic 
Value Constant Explanation 
0x1901 ERR 1901 invalid image number. 
0x1902 ERR 1902 image has no fields. 
0x1903 ERR 1903 could not open print file. 
Ox1904 ERR_1904 tried to Use TEMPP type that is already in use. 
0x1905 ERR_1905 could not allocate TEMPP type space for print screen. 


EXAMPLE | 
if ( (err=DT_IMGOT(muscreen,DTIMGALL,DTIMGREG,DTIMGREG)) ) 
printf("Could not display screen error = %x\n",err); 


SEE ALSO - 
DT CONST - output a constant field. 
DT FLDOT - output a variable field. 


REFERENCE NUMBER - 19 


d-tree Reference Guide 8-55 


DT INAME 
eee 


NAME 
DT_INAME- return the IMAGE number for the given string (DT_IMAGE.C) 


TYPE 
Table Validation 


DECLARATION 
COUNT DT_INAME(name) 
TEXT | *name; /* image name */ 


DESCRIPTION 

Given an image name, return the associated image number. This function simply 
does a lookup in the DT_GENRL table that contains the valid image names. If a 
match is found, the associated image number is returned, otherwise a zero is 
returned. 

RETURN 

NORMAL RETURN 

Image number associated with string. 

Zero for no match found. 


EXAMPLE 
if(!(menu =DT_INAME(mymenu'))) 
printf("mymenu was not defined in d-tree script"); 


REFERENCE NUMBER - 53 
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NAME 
DT_INBUF- Initialize a buffer. (KBDT_UTILY.C) 


TYPE 
Utility 


DECLARATION 

COUNT DT _INBUF(dp,n) //* initialize a buffer with nulls */ 
TEXT *dp; 

COUNT n; 


DESCRIPTION 
The specified region (string) of memory is set to nulls. 


RETURN 
Always returns a zero. 


EXAMPLE 

TEXT name[32]; 

DT_INBUF(name,32); /* set name field to nulls */ 
REFERENCE NUMBER - 36 


ideation OO oe ane eae kg 8 Dae ee ga re ew ee ee a ee ee 
d-tree Reference Guide 8-57 


DT INPUT 


NAME 

DT_INPUT-low level field input routine. (DT_INPUT.C) 

TYPE 

Screen Interface 

DECLARATION 

COUNT DT_INPUT(field,col,row,len,maxlen,inpatr,outatr, mask) 
TEXT *field; /* input buffer */ 

COUNT col; /* column on screen */ — 

COUNT row; /* row on screen */ 

COUNT len; /* screen length to input */ 

COUNT maxlen; /* max length to input */ 

COUNT inpatr; /* input arribute */ 

COUNT *outatr; /* pointer to output attributes array */ 
TEXT *mask; /* input mask for each char edit */ 
DESCRIPTION 


This function is used to maintain input for the specified field. It will position the 
cursor at the given coordinates, take into account input and output attributes, 
control input based on given lengths, allowing the contents of the variable field 
to be modified. 


RETURN 
Returns the last keystroke from the keyboard. 
EXAMPLE 
TEXT name[32]; 
exitkey =DT_INPUT(name, /* field */ 
12, /* column */ 
10, /* row */ 
30, /* screen length */ 
30, /* max length */ 
0, /* input attribute */ 
0); /* output attribute */ 


REFERENCE NUMBER - 4D 
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NAME 
DT_KEYBD- initialize screen and keyboard definitions from termcap file. 
(DT KEYBD.C) 


TYPE 

Export/Import 

DECLARATION 

COUNT DT KEYBD(termcap,terminal) 

TEXT *termcap; /* termcap file name */ 
TOM terminal; /* terminal name */ 
DESCRIPTION 


This function initializes the screen and keyboard definitions for the d-tree 
keyboard and screen routines. This function will read the specified termcap file 
name and look for the terminal name provided. When it finds the proper terminal 
definition, DTPKEYBD is called to parse in the definition. 


RETURN 

NORMAL RETURN 

Returns a zero for successful completion. 

ERROR RETURN 

Symbolic 

Value Constant Explanation 
Ox7201 ERR 7201 Could not open termcap file. 
Ox7202 ERR 7202 Terminal not found in termcap file. 
Ox7203 ERR_7203 Could not allocate temp parsing space. 
0x7101 ERR_7101 Could not allocate space for key seq. 
Ox7102 ERR_7102 Syntax error in termcap definition. 
0x7103_ ERR_7103 DT_MXSEQ not large enough in DT_TYPDF.H. 


EXAMPLE 
if (err=DT_KEYBD(TERMCAP, getenv('TERM’))) 


printf("\nError Occurred During TERMCAP Parse Error = %x\n",err); 
exit(1); 

} 

SEE ALSO - 

DTPKEYBD - Parse KEYBD definition. 


REFERENCE NUMBER - 72 
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NAME 
DT_KEYNM- Validate token as a valid key symbolic name. (DT_PARSE.C) 


TYPE 
Table Validation 


DECLARATION 
COUNT DT KEYNM(token) 
TEXT *token; /* token to validate */ 


DESCRIPTION 
This function checks to see if the token that was passed is a key symbolic name 
defined in the ISAM definition. 


RETURN 
lf a match is found, the associated key number is returned; otherwise a zero is 
returned indicating that the token is not a key symbolic name. 


EXAMPLE 
if (OPNISAM(EXAMPLE.P)) /* must open the isam for DT_ KEYNM to work */ 


t 


printf("\\n\nCould not open isam. Error codes %d %d",isam_err,isam_fil): 
exit(0); 


if (keyno = DT_KEYNM(token)) 

printf("Symbol %s refers to key number %d\n",keyno); 
else 

printf(‘Symbol %s IS NOT in valid key symbol name\n",token); 
if (CLISAM() 


printf("\n\nCould not close isam. Error codes %d %d",isam_err,isam_fil); 
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DT LOCAT 


NAME 
DT_LOCAT- Position the cursor on the screen. (DT_MISCI.C) 


TYPE 
Screen Interface 


DECLARATION 
COUNT DT LOCAT(col,row) 
COUNT col,row; /* row and column on screen */ 


DESCRIPTION 
This function will position the cursor at the given coordinates, utilizing the es- 
Cape sequences from the termcap file. 


RETURN 
NORMAL RETURN 
Returns a zero for successful completion. 
ERROR RETURN 
Symbolic 
Value Constant Explanation 
0x2401 ERR_2401_ Invalid screen coordinates. 


EXAMPLE 
DT LOCAT(10,01); /* position cursor at column 10 on row 1 */ 
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NAME 
DT_LOCPT- Position the cursor for stream output. (Locate for print output) 
(DT_MISCI.C) 


TYPE 

Screen Interface 

DECLARATION 

COUNT DT LOCPT(fp,col,row) 

FILE *fp; /* output file ptr */ 
COUNT col,row; /* column and row */ 
DESCRIPTION 


This function will position the cursor at the given coordinates pertaining to the 
output stream. It is primarily used when the print screen has been hit. 


RETURN 
Always returns a Zero. 


EXAMPLE | 
DT_LOCPT(fp,10,01); /* position cursor relative to column 10 on row 1 on printed 
page*/ 
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NAME 
DT_MAPDD- given two DODA symbolic names, map one field’s contents to 
another. (DT_WDODA.C) 


TYPE 

Data Management 

DECLARATION 

COUNT DT MAPDD(dsymb,ssymb) 

TEXT *dsymb; /* destination symbol */ 
TEAL *ssymb; /* source symbol */ 
DESCRIPTION 


This function simply determines the addresses associated with the two symbolic 
names and does a memory copy from the address of the source to the address 
of the destination. 


RETURN 
Returns a 1 if function failed. 
returns a zero if successful. 


EXAMPLE 
if (OT_MAPDD("myname","yourname’)) 
printf("Could not copy yourname to myname"); 
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NAME 
DT_MAPIT- execute field maps defined in given MAPIT definition. (DT _MAPIT.C) 


TYPE 
Data Management 


DECLARATION 
COUNT DT MAPIT(mapno) 
COUNT mapno; /* map definition to execute */ 


DESCRIPTION 

Using the MAPIT keyword in a d-tree script, fields that are to be copied to one 
another (mapped to one another) are defined. This function executes these 
copies(mapps) for the map definition associated to the given number. 


RETURN 
NORMAL RETURN 
Returns a zero for successful completion. 


ERROR RETURN 
Symbolic 
Value Constant Explanation 
0x961 ERR_961 Could not allocate space for extract. 


EXAMPLE 
if (mapno) DT_MAPIT(mapno); 
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NAME 

DT_MENUS- Display MENU and execute menu logic. (DT_MENUS.C) 
TYPE 

Special Ability 

DECLARATION 

COUNT DT MENUS(menusno,display) 

COUNT menusno; /* menu number to use */ 

COUNT display; /* display menu flag 1 =display 0 = no display*/ 
DESCRIPTION 


This function provides a menu interface for the programmer. MENUS screens 
and reactions are defined in a d-tree script. This function displays the proper 
IMAGE, accepts the input and executes the proper logic based on the input. 


d-tree script syntax: 


MENU(master) 

USES_IMAGE(menu) 

hg Call Criteria Type of Call Call Value */ 
option = 1 CURSOR = name EXECL my_program 
option=1 CURSOR =name SYSTEM | my_program 
option = 1 CURSOR = name CALL my_function 
option=1 CURSOR =name RETURN 1 


This function will react based on the- 
Type Of Calls 
EXECL - execute execl logic 
SYSTEM - execute a system call 
CALL - call another function 
RETURN - return a value from menu function 


RETURN 

NORMAL RETURN 

Returns value resulting from call to function, program, or menu 
otherwise, zero 


ERROR RETURN 
Symbolic 
Value Constant Explanation 
OxSF1 ERR _5F1_ Invalid MENUS number. 
OxSF2 ERR 5F2 Invalid Image number. 
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EXAMPLE 
switch (DT_MENUS(menuno, 1)) 


case 1: /* Process menu selection 1. */ 
} 
REFERENCE NUMBER - 5F 
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NAME 

DT_NSERT- Insert a character into a character array. (DT_UTILY.C) 
TYPE 

Utility 

DECLARATION 

COUNT DT NSERT(ch,string, pos) 

COUNT i /* character to insert */ 

TEXT *string; /* character array to insert character into */ 
COUNT pos; /* position in array to insert character */ 
DESCRIPTION 

This function inserts a character into a string after the specified position. 
EXAMPLE 

TEXT name[32]; 


strcpy(name,"abcdefg"); 
DT_NSERT(x’,name,1); 


yields... "axbcdefg" 
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NAME 
DT NXREC- Get the next record in a c-tree file. (DT_CTREE.C) 


TYPE 
File I/O 


DECLARATION 
COUNT DT NXREC¢(filno) 
COUNT filno; /* file number */ 


DESCRIPTION 

This function performs the following steps. 

a) calls c-tree’s NXTREC to get the record. if error on NXTREC return error. 

b) determines if the file is variable length or not. If variable length it then unpacks 
the record into the maintenance buffer otherwise its simply copies the read 
record into the maintenance buffer. 

Cc) if UNIFRMAT is define the uniformat logic is executed. 

d) DT_UNPAD is called to unpack fixed length fields. 


RETURN 

NORMAL RETURN 

Returns a zero for successful get. 
ERROR RETURN 

Returns the c-tree NXTREC error if failed. 


EXAMPLE 
if (1(OT_NXREC(keyno))) 
printf("Got next record"); 
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NAME 
DT_OFSET- calculate the offset of a given DODA entry. (DT _ALIGN.C) 


TYPE 
Doda Managment 


DECLARATION 

UCOUNT  DT_OFSET(ptrdoda, offset) 

DATOBJ *“ptrdoda; _/* pointer to doda entry */ 
UCOUNT _ offset: /* last fields offset */ 


DESCRIPTION 

This function is used to determine the offset of a field defined in the DODA. 
Given the DODA pointer to the field and the offset of the prior field, this function 
will calulate the offset of the given field and store the offset in the fhrc field in the 
DODA structure. This function is called by the alignment function DT ALIGN as 
it loops thru all the entries in the DODA. 


RETURN 
Returns the calculated offset. 


EXAMPLE 
offset = DT_OFSET(ptrdoda, offset): 
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DT PARSE 


NAME 

DT PARSE- Primary Parsing Function. (DT_PARSE.C) 
TYPE 

Parsing 

DECLARATION 

COUNT DT PARSE(scrptnam) 

TEXT *scrptnam; /* script file name */ 
DESCRIPTION 


This function is the primary parsing function whichs reads the d-tree script 
whose name was passed as the parameter. It scans for valid keywords that 
were defined in DT_VALID.H. For each valid keyword found it calls the 

DT _PBUFF function which load a temporary parsing buffer with this keywords 
definition and then calls the associated keyword parsing routine passing the 
pointer to this buffer and it’s length. Each keyword’s own parsing routine inter- 
prets this buffer and initializes it’s associated typedef. 


RETURN 
NORMAL RETURN 
Returns a zero if successful. 


ERROR RETURN 
if the parse fails, the error from the keyword parsing routine that failed is 
returned. 


Symbolic 
Value Constant Explanation 
1101 ERR-1101 fopen error 
1102 ERR-1102 no valid keyword found in script 
1103 ERR-1103 unable to allocate temp parsing buffer 


EXAMPLE 
if (err =DT PARSE(myscript)) 


printf("\nError Occured During Parse Error = %x\n",err); exit(1); 
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NAME 

DT_PBUFF- Load Temporary Parsing Buffer. (DT _PARSE.C) 
TYPE 

Parsing 

DECLARATION 

DITKEYWD *DT_PBUFF(parsebuf,fp,len,ch) 

TEXT *parsebuf; /* pointer to parsing buffer */ 
Pie di 2 /* source file pointer */ 

COUNT *len; /* length loaded into buffer */ 
COUNT gl 4 /* last char read from text file */ 
DESCRIPTION 


The purpose of this function is to load a temporary buffer that is to be used by a 
specific ability parsing routine. By looping on the DT TOKEN function the 
source file is read and each token is checked to see if it is a keyword. If so the 
loop terminates. Note the option of the DT TOKEN function. If a buffer address 
is passed as it’s third parameter, that buffer is loaded as it looks for the next 
keyword. The pointer to this temporary buffer is saved upon entry in order to to 
calculate the length of the buffer’s data upon return. Once a new keyword is 
found the function will return a pointer to that keyword’s structure. Because the 
address of len was passed, the calling function is able to utilize the calculated 
length of the temporary buffer. If EOF is hit, a return(0) will notify the calling 
function that there are no more keywords. 


This function is called by the master parsing function DT_ PARSE. The primary 
flow of DT_PARSE is to loop on this function as long as there are keywords. 
This function loads the temporary parsing buffer, providing it’s length and return- 
ing a pointer to the next keyword. DT_PARSE then calls the current keyword’s 
associated parsing routine, passing it the loaded buffer address and it’s length. 


RETURN 
0 - Hit EOF no nor keywords in source. 
ptr - Keyword stucture pointer to next keyword found in source. 
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EXAMPLE 
while (nxtptr)/* loop while keyword are hit */ 


len=0; /* reset parsing buffer length */ 

nxtptr=DT_PBUFF(parsebuf,fp,&len,&ch); /* load temp parsing buffer */ 

if (err = (*ptr-fptr) (ptr, parsebuf,len)) /* call keywords parsing funct */ 
return(err); /* if parse has error then return */ 

ptr =nxtptr; /* remember we are using function */ 


/* pointers here */ 
} /* end loop for keyword parsing */ 


SEE ALSO 
DT_PARSE - Primary Parsing Routine. 
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NAME 

DT_PRMPT- File Access Prompt Routine (DT _PRMPT.C) 

TYPE 

Special Ability 

DECLARATION 

COUNT DT_PRMPT(prmptno,keyno,scanno,target,tarsigIn) 
COUNT prmptno;  /* prompt number to use */ 

COUNT *keyno; /* key number to be used for get function */ 
COUNT *scanno;  /* scan number to use */ 

TEAL *target; /* target to be used for get function By 
COUNT *tarsigin; _/* target sig length */ 

DESCRIPTION 


This function displays the IMAGE specified in the d-tree script and accepts input 
from the user. Based on information defined in the script, this function will: 
a) Initialize a target (key) value to be used to access a c-tree file, doing all 
defined 
concatenations as well as executing c-tree’s TFRMKEY. 
b) set tarsigin to the defined significant length for the target. 
c) set keyno to the proper index (or data) file number. 
d) set scanno to the proper scan to use if there is a non-equal access to the file. 


RETURN 
NORMAL RETURN 
Returns the last keystroke from the keyboard. 
ERROR RETURN 
Symbolic 
Constant 
ERR 4001 
ERR 4002 
ERR_4003 
ERR 4004 
ERR 4005 


Explanation 

Prompt number not defined. 
Associated IMAGE not found. 

Prompt not found in extracted subset. 
Target fields not found for target build. 
Could not allocate space for extract. 


Value 

0x4001 
0x4002 
0x4003 
0x4004 
0x4005 
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EXAMPLE 
while ((DT_PRMPT(prompt,&keyno, &scann,target, &tarsigin))! = DTKBESC) 
{ 
err =0; 
if (keyno && !(DT EQREC(keyno,target))) 
{ err=1; } 
else 


if (!keyno) keyno = datno; 
if (!\(DT_SCANN(scann,keyno,target,tarsigIn)) ) { err=1; } 
} /* end not hit on eqlrec */ 

if (err) 


{ 
DTchgmode(mode); 
} /* end got a record */ 
DT DOINT(datno); option =0; 
} /* end prompt while */ 
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NAME 
DT_PSTFX- Convert an expression in infix to postfix form. (DT_PSTFX.C) 
TYPE 
Utility 
DECLARATION Tr 
COUNT DT PSTFX(in, sh 
TEXT *in; /* pointer to infix expression */ 
TEXT *out; /* pointer to postfix expression */ 
_ DESCRIPTION 


This function will convert an infix Vxpression to a postfix expression. Once an ex- 
pression is in postfix form, it is easier to evaluate. 


RETURN y 4 
always returns a zero. 

EXAMPLE 

given .... 


(((A/(B*C)) + (D*E))-(A*C)) 
DT PSTFX yeilds... 


ABC*/DE* + AC*- 
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NAME 

DT_PVREC- Get the previous record in a c-tree file. (DT _CTREE.C) 


TYPE 
File I/O 


DECLARATION 
COUNT DT _PVREC(filno) 
COUNT filno; /* file number */ 


DESCRIPTION 

This function performs the following steps. 

a) c-tree’s PRVREC to get the record. if error on PRVREC return error. 

b) Determines if the file is variable length or not. If variable length it then unpacks 
the record into the maintenance buffer otherwise it simply copies the read 
record into the maintenance buffer. 

c) if UNIFRMAT is defined the uniformat logic is executed. 

d) DT_UNPAD is called to unpack fixed length fields. 


RETURN 

NORMAL RETURN 

Returns a zero for sucessful get. 

ERROR RETURN 

Returns the c-tree PRVREC error if failed. 


EXAMPLE 
if (!(DT_PVREC(keyno))) 
printf("Got previous record"): 
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NAME 
DT_RCDLN- given the last potential offset for a file, return the record length. 
(DT_ALIGN.C) 


TYPE 
DODA Management 


DECLARATION 
UCOUNT DT RCDLN(offset) 
UCOUNT _ offset; /* next offset */ 


DESCRIPTION 

In the alignment functions, we loop thru the DODA entries determining the of- 
fsets of the fields. When the last field is calculated, offset is set to the next byte 
after the last field’s length. By passing this offset to the DT RCDLN function, the 
length of the record structure is returned. 


RETURN 
Returns the offset where the next structure would be aligned or in otherwords 
the structure length of the previous structure. 


EXAMPLE 

UCOUNT DT_ALDOD(dodaptr,noofflds) 

DATOBJ *dodaptr; /* pointer to first field in record */ 

COUNT noofflds; /* number of fields in record */ 

{ 
COUNT DT_STALN(): /* set alignment array */ 
UCOUNT DT_OFSET();_ /* calc field offsets */ 
UCOUNT DT_RCDLN();  /* calc record length */ 
COUNT offset =0; 
COUNT noindoda =0; 


DT STALN(O; 
while (dodaptr-fwhat! = -1) 


offset = DT_OFSET(dodaptr, offset); 

+ + noindoda: /* count number of entries in doda */ 
+ + dodaptr;/* next doda */ 

if (noindoda = =noofflds) break; 


return(DT_RCDLN(offset)); /* return record length */ 
} /* end function */ 
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NAME 
DT RDBUG- Relate Structure Debug. (DT DEBUG.C) 


TYPE 
Internal Structure Relationships 


DECLARATION 

COUNT DT RDBUG(adr,num) 

DTTRELAT *adr; /* relate structure base address */ 
COUNT num; /* number of relate occurances */ 


DESCRIPTION 

This function is used to display the given relate structure on the screen. The ad- 
dress of the RELAT strucure type as well as the number of elements in the 
RELAT array are given to this function. It is very useful in debugging programs 
which use relationships defined by the relate function. 


RETURN 
always returns a zero. 


EXAMPLE 
DT RDBUG(DTGRELAT,DTNRELAT); 
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NAME 
DT_REFMT- Reformat a file. (DT REFMT.C) 


TYPE 
Data Managment 


DECLARATION 
COUNT DT_REFMT(sdoda,sflds, sfilnam,ddoda,dflds,dfilnam) 
DATOBJ *sdoda; /* source doda */ 


COUNT sflds;: /* number of source fields */ 
TEXT *sfilnam; /* source file name */ 

DATOBJ *ddoda; /* destination doda */ 

COUNT dflds; /* number of destination fields */ 
COUNT *dfilnam; §_/* destination file name */ 
DESCRIPTION 


This function will reformat the definition of a c-tree file based on the definition 
provided in the two DODA’s that are passed. This function will reformat file’s in 
place. At this time fixed length files are supported. Variable length file support is 
being tested. 


RETURN 
NORMAL RETURN 
Returns a zero for sucessful completion. 


ERROR RETURN 
Symbolic 
Value Constant Explanation 
Ox6C1 ERR _6C1 Space Allocation error. 
Ox6C2 ERR_6C2 Could not Open Source file. 
Ox6C3 ERR_6C3 Doda Length Does not match Source File. 
Ox6C4 ERR _6C4 Source file not a data file. 
Ox6C5 ERR_6C5_ Source file Corrupt at open. 
Ox6C6 ERR_6C6 Could not read File header info. 
Ox6C7 ERR_6C7 Could not read Variable length record six byte header. 
Ox6C8 ERR_6C8 Source record READ error. 
Ox6C9_ ERR 6C9 Write of Null Header failed after format. 


EXAMPLE 
if ((c=DT_REFMT(oldfile,oldflds, oldnam,newfile,newflds,newnam))) 
return(c); 
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NAME 

DT _RSORT- Sort Relate Structure. (DT RELAT.C) 
TYPE 

Internal Structure Relationship 

DECLARATION 

COUNT DT RSORT( base, nel, width, mode) 
TEXT *base; 

COUNT nel, width, mode; 

DESCRIPTION 


This function is used to sort the relate typdef structure. 
Valid Modes- (defined in DT_TYPDF.H) 


#define DTQSLTYP 1 /* Sort by left side type. */ 

#define DTQSLTAC 2 /* Sort by left side type and count. */ 
#define DTQSLTAA 3 /* Sort by left side type and alt sort. */ 
#define DTQSLSRT 4 /* Sort by left side alt sort field. */ 

#define DTQSRTYP 5 /* Sort by right side type. */ 

#define DTQSRTAC6 = /* Sort by right side type and count. */ 
#define DTQSRTAA7 = /* Sort by right side type and alt sort. */ 
#define DTQSRSRT 8 ss /* Sort by right side alt sort field. */ 
#define DTQSBAAC9 _/* Sort by left side alt and right side cnt */ 
#define DTQSBCAC 10 /* Sort by left side cnt and right side cnt */ 
#define DTQSKYBD 11 _/* KEYBD sort-by terminal,key, no of gets */ 
#define DTQSHOOK 12 /* HOOKS sort-by spot (hook location) */ 


RETURN 
Always returns a zero. 


EXAMPLE 

/* Example taken from DTPKEYBD.C - Keyboard Parse routines. */ 

DT_RSORT(DTGPOINT[DTGCURGP][DTKKEYBD], 
DTGNNUMBR[DTGCURGP][DTKKEYBD], 
sizeof(DTTKEYBD), 
DTQSKYBD); 
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NAME 
DT_RTREE- r-tree front end prompt. (DT_RTREE.C) 


TYPE 

Special Ability 

DECLARATION 

COUNT DT RTREE(rtreeno) 

COUNT rtreeno; /* rtree number to use */ 


DESCRIPTION 

This function provides a front end to a r-tree report. The function first displays 
and accepts input from the IMAGE defined in the d-tree script. Based on the 
definition in the d-tree script it will then make the proper substitutions into the 
script and call the defined r-tree program. 


RETURN 
NORMAL RETURN 
normal return is zero, or DTKBESC if the <ESC> key was pressed 


ERROR RETURN 
Symbolic 

Value Constant Explanation 
Ox6E1 ERR_6E1_ rtree number not defined. 
Ox6E2 ERR_6E2_ associated IMAGE not found. 
Ox6E3_ ERR _6E3 _ rtree not found in extracted subset. 
Ox6E5 ERR_6E5_ could not allocate space for extract. 
Ox6E6 ERR _6E6~ could not open script work file. 
Ox6E7 ERR_6E7_ could not open base script file. 


EXAMPLE 

/* This will execute the balance sheet report. */ 
DT RTREE(DT_INAME(‘balsheet")); 
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NAME 
DT _RWREC- Add a record to the c-tree data base. (OT. CTREE.C) 


TYPE 
File /O 


DECLARATION 
COUNT = DT_RWREC(datno) 
COUNT datno;/* data file number to add record to. */ 


DESCRIPTION 

Rewrite a record back to a c-tree file. 

1) Pad the fields in the record buffer with the PADDING character from c-tree. 

2) Execute UNIFORMAT logic if defined by c-tree. 

) Determine the type of file record being written: either fixed or variable length. 

) If variable length file it will pack the record. _ 

) Enable record locking. LKISAM(ENABLE). 

6) Execute c-tree’s rewite record call. Either RWTREC or RWTVREC. 

7) Free the record lock. LKISAM(FREE). 

8) Commercial version will edit for muli-user interface with three buffer approach. 


RETURN 

NORMAL RETURN 

Returns a zero for successful rewrite. 

ERROR RETURN 

Returns the c-tree isam_err value if rewrite failed. 


EXAMPLE 
if (err=DT_RWREC(datno)) 
printf(target,"Unable to rewite record c-tree error = %d",err); 
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NAME 

DT SCANN- scan records in a c-tree file. (DT SCANN.C) 
TYPE 

Special Ability 

DECLARATION 

COUNT DT SCANN(scanno,filno,target,tarsig!n) 
COUNT scanno; /* scan number */ 
COUNT filno; /* file number */ 

TCAE *target; /* target for access */ 
COUNT tarsigIn; /* sig length of target */ 
DESCRIPTION 


This function provides an interface to a c-tree file for scanning the data records. 
Records are displayed and can be rolled up and down thru the data file. Option- 
ally maintenance may be performed on displayed records. This function provide 
a facility similar to the "browse" mode of some data base products. 


RETURN 

NORMAL RETURN 

returns a zero if record was selected. 
Returns a 1 if not record was selected. 
ERROR RETURN 


Symbolic 
Value Constant Explanation 
0x4101 ERR 4101 Scann number not a defined by SCANN 
0x4102 ERR 4102 IMAGE _OUT display failed. 


0x4103 ERR _4103 EQLREC failed on prev displayed rcd. 
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EXAMPLE 

while ((DT_PRMPT(prompt,&keyno, &scann,target, &tarsigIn))! =DTKBESC) 
err =0; 
if (keyno && !(DT_EQREC(keyno,target))) { err=1; } /* end if hit on eqlrec */ 
else 


if (!keyno) keyno = datno; 
if (!(DT_SCANN(scann,keyno,target,tarsigIn)) ) { err=1; } 
/* err=1 means got record on scann */ 
} /* end not hit on eqlrec */ 
if (err) | 


DTchgmode(mode); 

} /* end got a record */ 
DT_DOINT(datno); option =0; 
} /* end prompt while */ 
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NAME 
DT_SCGET- function used by DT_SCANN to get a selected c-tree record. 
(DT_SCANN.C) 


TYPE 

Special Ability 

DECLARATION 

COUNT DT_ SCGET(keyno,datno,recptr, prev) 

COUNT keyno; /* key number to get from */ 

COUNT datno; /* data file number */ 

TEXT *recptr; /* record buffer to read into */ 
COUNT prev; /* records prev is the record to get */ 
DESCRIPTION 


When a record is selected in the scan logic, this function will locate it in the file 
and read the selected record. 


RETURN 
NORMAL RETURN 
returns a zero if record was found. 
ERROR RETURN 
Symbolic 
Value Constant Explanation 
0x4901 ERR 4901 EQLREC Failed. 


EXAMPLE 
if (OT_SCGET(keyno,datno,recptr, (nosel-1))) 
return(ERR_4103); 
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NAME 

DT _SCSEQ- Output a special control sequence. (DT_MISCI.C) 
TYPE 

Screen I/O 

DECLARATION 

COUNT DT SCSEQ(fp,scseq) 

FILE *fp; /* file for output */ 

COUNT scseq; — /* special sequence number */ 
DESCRIPTION 


This function outputs to the given file pointer (stdout) the special character se- 
quence define by the given number. Special character sequences are initialized 
by DTPKEYBD from the termcap file for functions such as clear screen or draw 
a frame. 


RETURN 

NORMAL RETURN 

returns zero for sucessful completion. 

ERROR RETURN 

Returns a 1 in scseq is not a valid special sequence number. 


EXAMPLE 
Here is the clear screen function. 


COUNT DT_CLEAR() /* clear screen */ 


{ 
FAST COUNT c; 


FAST DTTKEYBD *kptr; 


kptr = (DTGKEYBD-DTSCCLS + DTSCFRS); 
putchar(kptr-retcode); 
for (Cc =0; c<kptr->noofchar; + +c) 


putchar(kptr-addchar{c]); 


return(0); 
} 
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NAME 
DT_SETTY- initialize tty mode (UNIX) (DT_MISCI.C) 


TYPE 
Keyboard Input 


DECLARATION 
COUNT DT SETTY(mode) 
FAST COUNT mode;/* set mode */ 


DESCRIPTION 

This function is called at the beginning of a program to set the I/O modes of the 
tty line on a UNIX system. It can be used for other startup and clean up func- 
tions. In the d-tree model programs, DT _SETTY(1) is calléd at the beginning of 
each program and DT_SETTY(0) is called at the end of each program. 


RETURN 
Always returns a zero. 


EXAMPLE 
DT _SETTY(1): 


REFERENCE NUMBER - 52 
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DT SFCAD 


NAME 
DT_SFCAD- Subfile Child Add Routine. (DT _SUBFL.C) 


TYPE 
Subfile 


DECLARATION 

COUNT DT SFCAD(parent,ocur, child) 
COUNT parent; /* parent subfile */ 
COUNT ocur; /* parent occurrence */ 
COUNT child; /* parent subfile */ 


DESCRIPTION 

This function writes all the records in a child subfile. Looping thru each record in 
the parent subfile, this function then accesses the subordinate records in the 
child subfile and executes the subfile record add function DT_SFHAD. 


RETURN 
NORMAL RETURN 
return the number of records added. 
ERROR RETURN | 
returns zero if subfile not found or allocated. 
(value of uerr_cod) 
Symbolic 
Value Constant Explanation 
Ox1E01 ERR_1E01 Invalid Parent subfile. 
Ox1E02 ERR_1E02 Parent not yet allocated. 
Ox1E03 ERR_1E03 Invalid child subfile. 
Ox1E04 ERR_1E04 Child not yet allocated. 


EXAMPLE 
DT_SFCAD(sfl2,ocur,sfl3); 


REFERENCE NUMBER - 1E 
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DT SFCLD © 


NAME 

DT SFCLD- Load Child Subfile. (OT SUBFL.C) 
TYPE 

Subfile 

DECLARATION 

COUNT DT SFCLD(parent,ocur,child,mode) 
COUNT parent; /* parent subfile */ 
COUNT Ocur; /* occurrence of parent */ 
COUNT child; /* parent subfile */ 
COUNT mode; /* subfile load mode */ 
DESCRIPTION 


This function loads records into a child subfile. By looping thru the parent sub- 
file, the target value for the child read is obtained. The child subfile is then 
loaded with proper records. 

Subfile load modes: 

DTSFLLIN - Subfile load initialize block only. 

DTSFLLOD - Subfile load data from disk. 


RETURN 
NORMAL RETURN 
Returns a zero if successful. 
ERROR RETURN (value of uerr_cod) 
Symbolic 
Value Constant Explanation 
0x1D01 ERR_1D01 DT SFCLD-Invalid Parent subfile 
0x1D02 ERR_1D02 DT SFCLD-Invalid Child subfile 
0x1D03 ERR_1D03 DT _SFCLD-Parent not yet allocated 
via DT_SFHLD: 
Symbolic 
Value Constant Explanation 
0x5901 ERR 5901 DT SFHLD-Invalid subfile number 
0x5902 ERR_5902 DT SFHLD-Could not allocate extract space 
Ox5903 ERR_5903 DT _SFHLD-Could not allocate memory control block 
Ox5904 ERR_5904 DT _SFHLD-Occurrences number out of range 


EXAMPLE 
DT SFCLD(sfl2,ocur,sfl3, DTSFLLIN); 


REFERENCE NUMBER - 1D 
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DT SFHAD 


NAME 
DT_SFHAD- Subfile High Level Add (DT _SUBFL.C) 


TYPE 
Subfile 


DECLARATION 

COUNT DT_SFHAD(sfino,ocur) 
COUNT sflno; /* subfile number */ 
COUNT ocur; /* subfile occurrence */ 


DESCRIPTION 

This function loops thru the records in a subfile and calls DT SFLAD (subfile low 
level add) for each record. The result is that every record in the subfile will be 
written to disk. 


RETURN 
NORMAL RETURN 
lf uerr_cod = zero then return value is number of records added. 
ERROR RETURN (value of uerr_cod) 
Symbolic 

Value Constant Explanation 

0x6101 ERR_6101 Invalid subfile number. 

0x6102 ERR 6102 Subfile not allocated. 


via DT_SFLAD: 
0x5801 ERR_5801 Could not allocate space for extract. 


EXAMPLE 
DT_SFHAD(sfl1,ocur); 


REFERENCE NUMBER - 61 
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DT SFHDL 


NAME | 
DT_SFHDL- Subfile High Level Delete. (DT _SUBFL.C) 


TYPE 
Subfile 


DECLARATION 
COUNT DT SFHDL(sfino) 
COUNT sflno; /* subfile number */ 


DESCRIPTION 

This function will delete all records that were previously loaded into it from the c- 
tree file. This function is usually called when an array of records was loaded into 
a subfile, the subfile was maintained, and it is time to update the disk with the 
changed records in the subfile. The current d-tree approach is to delete all 
records that were loaded and to rewrite the changes to disk as a series of adds. 
This function will do the delete. 


RETURN 
NORMAL RETURN 
If uerr_ cod = zero, then return value is number of records deleted. 
ERROR RETURN (value of uerr_cod) 
Symbolic 
Value Constant Explanation 
0x6001 ERR 6001 Invalid subfile number. 
Ox6002 ERR 6002 Subfile not allocated. 
0x6003 ERR 6003 No of rcds loaded into sfl not same as the no deleted. 


EXAMPLE 
DT SFHDL(sfl2); 


REFERENCE NUMBER - 60. 
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DT SFHLD 


‘NAME 

DT SFHLD- Subfile High Level Load (DT-SUBFL.C) 
TYPE 

Subfile’ 

DECLARATION 

COUNT DT SFHLD(sfino,ocur,mode) 

COUNT sfilno; /* subfile number */ 
COUNT Ocur; /* occurrence */ 

COUNT mode; /* load mode */ 
DESCRIPTION 


This function loads records from a c-tree file into a subfile based on the defini- 
tion provided from the d-tree script. This function allocates the memory space 
for the subfile and then calls the subfile low level function (DT _SFLLD) to load 
the records. 

Subfile load modes: 

DTSFLLIN - subfile load initilize block only. 

DTSFLLOD - Subfile load data from disk. 


RETURN 
NORMAL RETURN 
Returns c-tree’s uerr_cod if error. 
ERROR RETURN (value of uerr_cod) 
Symbolic 
Value Constant Explanation 
0x5901 ERR_5901_ Invalid subfile number. 
0x5902 ERR_5902 Could not allocate extract space. 
0x5903 ERR_5903 Could not allocate memory control block. 
0x5904 ERR_5904 Occur Number out of range. 


EXAMPLE 
DT SFHLD(sfl1,0,DTSFLLOD); 


REFERENCE NUMBER - 59 
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DT SFLAD 


NAME 
DT_SFLAD- Subfile Low Level Add (DT_SUBFL.C) 


TYPE 
Subfile 


DECLARATION 

COUNT DT_SFLAD(ptr,datno,norcds,sfloccur) 
DTTSUBSB *ptr; /* pointer to memory buffer */ 
COUNT datno;/* data file to add record to */ 


COUNT norcds; /* number of records to add */ 
COUNT sfloccur; /* subfile number */ 
DESCRIPTION 


This function adds records from a subfile to a c-tree file. As each record in the 
subfile memory area is processed, the subfile must have (SFL_MUSTHAVE) 
logic is executed to see if the record should be added. If it passes this test, then 
the SFL_MAP logic is executed to map data into the record before it is added. 
DT ADREC is then called to add the record. 


RETURN 
NORMAL RETURN 
If uerr_cod = zero, then return value is number of records added. 
If zero is returned then check uerr_cod for error. 
ERROR RETURN (value of uerr_cod) 
Symbolic 
Value Constant Explanation 
0x5801 ERR 5801 Could not allocate space for extract. 
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EXAMPLE 

Here is the subfile high level function that calls this function. 
COUNT DT_SFHAD(sflno,ocur) 

COUNT sfino; /* subfile number */ 

COUNT ocur; /* subfile occurrence */ 


COUNT DT SFLAD(); 

FAST DTTSUBFL *sptr; /* subfile work pointer */ 
FAST COUNT c; /* work counter */ 

uerr_ cod =0; 

sptr = DTGSUBFL; 

for (C=0; c<DTNSUBFL; + +c) 


if (sptr-num = =sflno) 
{ c = -1; break; } 
+ +S); 


I 
if (c! =-1) 


uerr_ cod=ERR_ 6101; 
return(0); 


sptr-sptr = sptr-ctlptr + ocur; 
if (!sptr-sptr || !sptr-sptr-sptr) 

{ uerr_cod =ERR_6102; return(0); } 
eMspimancds 
sptr-maxrcds, . i 

((COUNT) (sptr-DTGSUBFL)) 


REFERENCE NUMBER - 58 
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DT SFLDL 


NAME 

DT_SFLDL- Subfile Low Level Delete (DT _SUBFL.C) 
TYPE 

Subfile 

DECLARATION 

COUNT DT_SFLDL(keyno,target,tarsigIn) 

COUNT keyno; /* key number for load */ 
TEXT *target; /* target for c-tree set funct */ 
COUNT tarsigIn; /* target significant length */ 
DESCRIPTION 


This function deletes a group of related records from a c-tree file. With the 
passed parameters, this function loops thru the set of related records using c- 
tree’s FRSSET & NXTSET logic to delete the records. 


RETURN 
If zero is returned, check c-tree’s uerr_cod for error. 
If uerr_cod is zero the the number of records deleted is returned. 


EXAMPLE 
if ((nofound = DT_SFLDL(sptr-keyno, sptr-sptr-target, sptr-sptr-tarsigIn)) 
! = sptr-sptr-noofrcds) 


{ 

printf('‘Loaded %d rcds but Deleted %d rcds\n", 
sptr-sptr-noofrcds,nofound); getchar(); 

uerr_ cod=ERR 6003; 


I 
REFERENCE NUMBER - 57 
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DT SFLLD 


NAME 

DT_SFLLD- Low Level Subfile Load (DT _SUBFL.C) 

TYPE 

Subfile 

DECLARATION 

TEXT 

*DT_SFLLD(keyno, taret,tarigin, memopt, oldptr,sflrcdin,maxrcds,nofound, sfldatno) 
COUNT keyno; /* key number for load */ 

TEAT *target; /* target for c-tree set funct */ 


COUNT tarsigIn; /* target sig length */ 
COUNT memopt; /* memory option */ 


TEXF *oldptr; /* subfile memory blk ptr */ 
COUNT sfircdin; /* sfl record length */ 

COUNT maxrcds; /* number of sfl records */ 
COUNT *nofound; /* number of record loaded */ 
COUNT sfldatno; /* sfl dat file number */ 
DESCRIPTION 


This function uses c-tree’s set functions to access the file and load the memory 
area with the group of related records. 
Subfile memory allocation modes 
DTSFLANW - allocate new 

(clear old subfile memory block and allocate new block) 
DTSFLAMR - allocate more 

(leave old memory block active and allocate new block) 
DTSFLANO - allocate none 

(if there is a memory block clear and reuse it else allocate block) 
DTSFLAIN - allocate init 

(if there is a memory block clear and reuse it else allocate block 

then return with ptr - do not load data from disk) 


RETURN 
NORMAL RETURN 
Returns a zero if error occurred and error number is in uerr_Cod. 
Return the pointer to the memory block upon sucessful completion. 
ERROR RETURN (Value of uerr_cod) 
Symbolic 

Value Constant Explanation 

Ox5601 ERR_5601 Could not allocate space for sfl. 

Ox5602 ERR_5602 Memory Block Option is Invalid. 


EXAMPLE 
sptr=DT_SFLLD(0,NULL,O,DTSFLAIN, sptr,sflrcdin, maxrcds, &nofound ,0); 


-__—_———— eee 
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OT SFLLD 


REFERENCE NUMBER - 56° 
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DT SFLOT 


NAME 

DT_SFLOT- Subfile Out (Display a subfile) (DT _SUBFL.C) 
TYPE 

Subfile 

DECLARATION 

COUNT DT_SFLOT(sfino,sfinxt,sflrcd,logging,title) 
COUNT sflno; /* subfile number */ 

COUNT sflnxt; /* subfile child number */ 
COUNT sflrcd; /* subfile record number to start with */ 
COUNT logging; /* image logging special flag */ 
COUNT title; /* display title */ 
DESCRIPTION 


This function displays a subfile on the screen. If a child subfile is specified 
(sflnxt), it is also displayed. If the title flag =1, then the image defined in the d- 
tree script as a subfile title will be displayed. If the title flag >1, then it is as- 
sumed to be an image number and that image is displayed. 

Image Logging modes: 

DTIMGREG - special-nothing special for image out. 

DTIMGLOG - special-displaying from log-do not log. 

DTIMGSFL - special-image being displayed is subfile. 

DTIMGNOL - special-No Log-do not log image. 


RETURN 

NORMAL RETURN 

Returns the number of records displayed. 

ERROR RETURN 

Symbolic 

Value Constant Explanation 
0x6201 ERR_6201 Invalid subfile number. 
0x6202 ERR 6202 Subfile not allocated. 
Ox6203 ERR 6203 Must pass record number. 
0x6204 ERR_6204 Record number greater than max records. 
0x6205 ERR_6205 Invalid image number for subfile. 
Ox6206 ERR_6206 Child subfile number invalid. 
Ox6207 ERR_6207 Parent rcdno is child occurances. 


EXAMPLE 
DT_SFLOT (livesfl,livesub, 1,DTIMGSFL, 1); 


REFERENCE NUMBER - 62 
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DT SPTRS 


NAME 
DT_SPTRS- Reset pointers in RELAT structure. (DT_SPTRS.C) 


TYPE 
Internal Structure Relationships 


DECLARATION 
COUNT DT SPTRS() 


DESCRIPTION 
This function loops thru the RELAT strcutre and resets all the pointers to the as- 
sociated structures. 


RETURN 
Always returns a zero. 


EXAMPLE 
CODE = DT _SPTRS(Q; 


REFERENCE NUMBER - 22 
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DT STALN 


NAME 
DT STALN- Set Alignment Array. (DT_ALIGN.C) 


TYPE 
Doda Management 


DECLARATION 
COUNT DT STALN() /* set alignment array */ 


DESCRIPTION 
This function initializes the alignment array that is used to determine field type 
alignment based on the hardware. 


RETURN 
NORMAL RETURN 
Returns a zero if successful. 
ERROR RETURN 
Symbolic 
Value Constant Explanation 
0x8801 ERR 8801 COUNT, UCOUNT or POINTER are not correctly sized. 
Call Faircom. 
Ox8802 ERR_8802 This machine addresses 32 bit words (not bytes). 
Call FairCom. 
0x8803 ERR_8803 This machine addresses words.(not bytes). 
Call FairCom. 
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DT STALN 


EXAMPLE 

Here is the align doda function. 

UCOUNT DT ALDOD(dodaptr,noofflds) 

DATOBJ *dodaptr; /* pointer to first field in record */ 

COUNT noofflds; /* number of fields in record */ 

{ ‘ 
COUNT DT_STALNO; /* set alignment array */ 
UCOUNT DT OFSET();_ /* calc field offsets */ 
UCOUNT DT RCDLN(); /* calc record length */ 
COUNT offset =0; 

COUNT noindoda=0; 
DT STALN(); 
while (dodaptr-fwhat! = -1) 


{ 

offset =DT_ OFSET(dodaptr, offset); 

+ +noindoda; /* count number of entries in doda */ 
+ + dodaptr;/* next doda */ 

if (noindoda = =noofflds) break; 


} 
if (noofflds) | 
return(DT RCDLN(offset)); /* return record length */ 
else 
return(noindoda + 1); /* return number of fields in doda */ 
/* add one for terminator */ 
} /* end function */ 


REFERENCE NUMBER - 88 
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DT SUBFL 


NAME 

DT_SUBFL- Maintain a Subfile (DT SUBFL.C) 

TYPE 

Subfile 

DECLARATION 

COUNT DT SUBFL(sflno,sflnxt,logging) 

COUNT sfino; /* subfile number */ 

COUNT sflnxt; /* subfile number */ 

COUNT logging; /* immage logging special flag */ 
DESCRIPTION 


This function is used to maintain a subfile. Cursor control for moving from field 
to field (as well as roll up and roll down) is handled by this function. 


RETURN 
NORMAL RETURN 
Returns the last keystroke from the keyboard. 
ERROR RETURN 
Symbolic 
Value Constant Explanation 
0x6401 ERR_6401 Invalid Subfile Number. 
Ox6402 ERR_6402 Subfile Not Allocated. 
Ox6403 ERR 6403 Invalid Image define for Subfile. 
0x6404 ERR_6404 Could not allocate temp save space. 


EXAMPLE 
if ( (err=DT_SUBFLilivesfl,livesub, DTIMGSFL) ) = = DTKBESC) 
printf("escape hit from subfile"); 


REFERENCE NUMBER - 64 
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DT SUBIT 


NAME | 
DT SUBIT- Subtract one field from another based on DODA symbol names. 
(doubles only) (DT WDODA.C) 


TYPE 

Data Management 

DECLARATION 

COUNT DT SUBIT(dsymb,ssymb) 

TEXT *dsymb; /* destination symbol */ 
TEXT *ssymb; /* source symbol */ 
DESCRIPTION 


Given two DODA symbolic names, subtract the value of the second from the 
first. This function uses DT_TDODA to get the addresses of the symbol names 
and then does the subtraction. The result is that the value at the destination 
symbols’s address has now been decremented by the value at the source’s ad- 
dress. This function assumes that the symbols being passed are of double type. 
Use this as an example if other types are needed. 


RETURN 

NORMAL RETURN 

Returns a zero if successful. 
ERROR RETURN 

Returns a 1 if error. 


EXAMPLE 
if (DT_SUBIT("F1400a","F703a")) 
printf(Could not subtract the two values."); 


SEE ALSO 
DT TDODA 


REFERENCE NUMBER - 5A 
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DT TDODA 


NAME 

DT_TDODA- Validate token as a symbolic name in DODA. (DT WDODA.C) 
TYPE 

Table Validation 

DECLARATION a 

DATOBJ *DT_ TDODA(dodaptr,token) ‘ 

DATOBJ *dodaptr; /* pointer to DODA */ 

TEXT *token; /* token to validate */ 

DESCRIPTION 


This function simply does a "LOOKUP" on the Data Object Definition Array 
(DODA) to see if the token passed is defined in the DODA as a variable sym- 
bolic name. 


RETURN 

NORMAL RETURN 

Returns pointer to the corresponding DODA entry. 
ERROR RETURN 

Returns Zero if item is not found in the DODA. 
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DT TDODA 


EXAMPLE 
Example- Check parameter passed to pgm as valid symbol in DODA. 
#include "DT DEFIN.H" 


char NUMBER[11]; 
char NAME[26]; 
char CODE[5]; 


DATOBJ doda[] = { 
{"Cust_Num", NUMBER, RTSTRING, 11}, 
{"Cust_Name", NAME, RTSTRING, 26}, 
{"Cust_ Code", CODE, RTSTRING, 5}, 


te AOI 
If 
void main(argce, argv) 
int argc; 


char *argv{]; 


DATOBJ *DT_ TDODA(),*ptr; 
TEXT token[32]; 
strcpy(token,argv[1]); 


if (ptr =DT_TOKKW(token)) 
printf("Symbol %s IS in DODA\n", ptr-fsymb); 
else | 
printf("Symbol %s IS NOT in DODA\n",token); 
} /* end pgm */ 


REFERENCE NUMBER - 17 
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DT TODAY 


NAME 
DT_TODAY- Access System Date and Time. (DT _UTILY.C) 


TYPE 

Utility 

DECLARATION 

COUNT DT_TODAY(date1,mode) /* get date in string format */ 
TEXT *date1; 

COUNT mode; 


DESCRIPTION 
This function places system date/time information into the first parameter based 
upon the second parameter (mode). Valid modes are: 
0 - month-day-year (mmddyy) 
1 - hour-min-sec (hhmmss) 
2 - year-mon-day-hour-min-sec (yymmddhhmmss) 
3 - string form 
4 - month/day/year (mm/dd/yy) 
RETURN 
Always reaturns zero. 
EXAMPLE 
TEXT DATEFLD{8]; 


DT_TODAY(DATEFLD, 0); 
REFERENCE NUMBER - 5C 
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DT TOKEN 


NAME 

DT _TOKEN- Get the next token from a Text file. (DT TOKEN.C) 
TYPE 

Parsing 

DECLARATION 

COUNT DT TOKEN (fp,token,load, buffer, strbuf,ch) 
FILE ote /* file pointer for source */ 

TEXT *token; /* buffer to hold token */ 
COUNT load; /* load temp parse buffer flag */ 
FAST TEXT **buffer; /* ptr to ptr to work buffer */ | 
TEXT *strbuf; /* beginning of parseing buffer */ 
COUNT *ch; /* last char read from text file */ 
DESCRIPTION 


This function will read the text file pointed to by *fp and place the next token 
into the variable passed as the second parmeter. By token we mean the next 
set of characters that are separated on both sides by white space character 
(each word or symbol). A white space character is one of the following: space, 
new line (‘\n’), carrige return (’\r’), and horizontal tab (’\t’). Comments (/* ... */) 
are ignored. If an address to a buffer is provided as the last parameter, all 
characters including white spaces, but not including comments, are placed in 
the buffer. This function is used by the primary parsing routine (DT PARSE) and 
the load parsing buffer routine(DT_PBUFF). 


RETURN 
This function returns the length of the token found. A value of zero means that 
end of file (EOF) was reached with no token found. 
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DT TOKEN 


EXAMPLE 

/* Example- Print all tokens in sample file FILE.TXT */ 
#include "stdio.h" 

main() 


{ 
FILE *fp, *fopen(); 
COUNT DT_TOKEN(; 


if ((fp = fopen("FILE.TXT","r')) = = NULL) 
exit(1) 


while (DT_TOKEN(fp,token,0)) 


printf(‘Token = %s\n",token); 
} /* end looping thru tokens */ 


} /* end pgm */ 
REFERENCE NUMBER - 12 
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NAME 
DT TOKKW- Validate token as Keyword. (DT_PARSE.C) 


TYPE 
Parsing 


DECLARATION 
DTTKEYWD *DT TOKKW(token) 
TEXT *token; /* token to check */ 


DESCRIPTION 

This function is used to validate keywords. Simply pass the variable to be check- 
ed to this function and it will return(0) if it is an invalid keyword or a pointer of 
type DITKEYWD that point to the structure occurance in which this keyword 
was found. The logic scans the valid keywords defined in DT _VALID.H. If the 
token contains a (x) at the end ( as in IMAGE(1) ) then (X) is dropped before 
token is compared. 


EXAMPLE 
/* Example- Check parameter passed to pgm as valid keyword */ 


#include "DT _DEFIN.H" 
#include "DT _VALID.H" 


void main(argce, argv) 
int argc; 
char *argv{]; 


DTTKEYWD *ptr,DT TOKKW(); 
TEXT token[32]; 


strcpy(token,argv[1]); 
if (ptr =DT TOKKW(token)) 
printf(Variable %s IS a valid keyword\n", ptr-keyword); 


else 
printf(Variable %s 1S NOT a valid keyword\n'",token); 


} /* end pgm */ 
REFERENCE NUMBER - 13 
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DT TOKNX 


NAME | , 

DT_TOKNX- Get the next token from memory buffer. (DT_TOKEN.C) 
TYPE 

Parsing 

DECLARATION 

COUNT DT_TOKNX(token,strbuf,endbuf,space,tab,cr,nl,termnl) 
TEXT *token; /* Field pointer to return token in*/ 

TEAT **strbuf; /* starting pointer into buffer */ 

TEXT **endbuf; /* ending pointer into buffer */ 

COUNT *space, *tab,*cr, *nl,*term; /* ptrs to counters*/ 
DESCRIPTION 


This function is used to get the next token from a memory buffer, starting at the 
strbuf position and terminating it’s scan at the endbuf position. As it scans it will 
count the number of separate white space characters (spaces ,tabs ,carriage 
returns, and new lines) encountered. A COUNT variable for each one of these 
must be defined in the calling function and the address of each variable passed. 
This function will then update these variables with the number of each type en- 
countered until a token was found. Note that spaces and tabs are the count 
since the last new line was encountered. 


The results of this call are the following- 
- variable token contains the next token or is NULL. 


- the counter variables tell you how many of the associated white spaces were 
hit before the token was found.(spaces & tabs are re-set to zero when newline is 
hit). 


- the function returns the length of the token or zero for no token found. 
- the strbuf pointer has been positioned to the first white space after the token 


or is equal to endbuf. 


RETURN 
This function returns the length of the token found. A value of zero means that 
end buffer pointer was reached with no token found. 
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EXAMPLE 
/* Example- Print all tokens in buffer. */ 


#include "DT _DEFIN.H" 
main() 


{ 

COUNT DT_TOKNX(; 

TEXT buffer[64]; 

TEXT *strbuf,*endbuf; 

COUNT space,tab,cr,nl;_ /* pointers to counters */ 
COUNT len: 


strcpy("This is the Buffer we will look at for tokens", buffer); 


strbuf = buffer; 
endbuf = strbuf + strlen(buffer); 


while (len=DT_TOKNX(token, &strbuf, &endbuf,&space, &tab, &cr, &nl)) 


printf("Token ='%s’\n",token); 

printf(‘Token is %d characters long\n'); 

printf("Token is on line %d\n",nl + 1); 

printf(Token is in position %d\n",(tabs*5) + space); 
} /* end looping thru tokens */ 


} /* end pgm */ 
REFERENCE NUMBER - 15 
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NAME 

DT_TSPLT- Split a token. (DT TOKEN.C) | 

TYPE 

Parsing 

DECLARATION 

COUNT DT_TSPLT(token,getocur,addit) 

TEXT *token; /* token to split */ 

COUNT getocur; /* split flag */ 

COUNT addit; /* add to general table flag */ 
DESCRIPTION 


This function will take a token in the form ABCDE(1) and return ABCDE and the 
1. This function is used in parsing abilities. 


RETURN 

This function returns the value found between the parentheses "()". Ifa sym- 
bolic reference if found instead of a numeric value, it is evaluated to determine 
the proper numeric value. 


EXAMPLE 
ocur = DT_TSPLT(token,1,0); | /* takes CHAR(5) and returns */ 
/* token ="CHAR" and ocur=5 */ 


REFERENCE NUMBER - 65 
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DT UNPAD 


NAME 
DT UNPAD- Unpad a record structure. (DT _CTREE.C) 


TYPE 
File I/O 


DECLARATION 


COUNT DT UNPAD(datno) /* un-pad a record */ 
COUNT datno; 


DESCRIPTION 

This function will strip off the padding characters from the end of all string type 
fields in the specified data file record buffer. 

RETURN 

Always returns a zero. 


EXAMPLE 
DT _UNPAD(datno): 


REFERENCE NUMBER - 5B 
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NAME 

DT_UNPAK- Unpack one record structure into another. (DT_CTREE.C) 
aYPc 

File I/O 

DECLARATION 

COUNT DT_UNPAK(base, end, length, fixed, frmbuf,tobuf) 
DATOBJ *base; /* starting doda pointer */ 

DATOBJ *end; /* ending doda pointer */ 

UCOUNT length; /* structure length of destination buffer */ 
UCOUNT _ fixed; /* fixed length portion of record */ 
COUNT frmbuf; /* from buffer number */ 

COUNT tobuf; /* to buffer number */ 

DESCRIPTION 


This function is used to unpack a variable length record once it is read into a 
buffer from disk, into the record maintenance buffer. It is called from DT VLINN 
when a variable length record has been read from disk and needs to be unpack- 
edc. 


RETURN 
Always returns a zero. 


EXAMPLE 
COUNT DT_VLINN(datno) 
COUNT datno; 


{ 
COUNT DT_UNPAK(),DT_INBUF(): 


DT_INBUF(dt_sfp[datno]-fadr + dt_sIn[datno],dt_ sin [datno]); 
if (REDVREC(datno,dt_sfp[datno]-fadr + dt_sIn[datno],dt_sIn[datno}) ) 
return(ERR_ 3201); 


/* unpack from 1 to 0 */ 
DT_UNPAK(dt_sfp[datno],dt_efp[datno] ,dt_sIn[datno], (key + datno)-reclen, 1,0): 
return(0); 


} 
REFERENCE NUMBER - 33 
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NAME 
DT _VLINN- read and unpack the variable length portion of a c-tree variable 
length record. (DT _CTREE.C) 


TYPE 
File I/O 


DECLARATION 
COUNT DT VLINN(datno) 
COUNT datno; 


DESCRIPTION 
When a record is read from a c-tree file, this function is called if the record is a 
variable length record. The variable length portion of the record is read and the 
function DT_UNPAK is called to unpack the record for maintenance. 
RETURN 
ERROR RETURN 
Symbolic 
Value Constant Explanation 
0x3201 ERR_3201 REDVREC failed. see uerr_cod. 
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EXAMPLE 

Note the d-tree equal record function. 
COUNT DT_EQREC(keyno,target) 

COUNT keyno; /* key number for get */ 
TEXT *target; /* target to use for get */ 


COUNT DT_UNPAD(); /* un-padd a record */ 
VOID cpybuf(); 
COUNT EQLREC(; 
COUNT DT_VLINNO; 
COUNT datno; 
COUNT error; 


datno = revmap[keyno]; /* find data file number for this key */ 
if ((error = EQLREC(keyno,target,dt_sfp[datno]-fadr + dt_sln[datno]))) 
return(error); 


/* if variable length data */ 
if ((key + datno)-clstyp = =VAT_CLOSE) 
DT VLINN(datno); 
else /* copy record buffer */ 
cpybuf(dt_sfp[datno]-fadr, 
dt_sfp[datno]-fadr + dt_sIn[datno], 
dt_sln[datno]}): 


# ifdef UNIFRMAT 
unifrmat(datno); 
# endif 


DT_UNPAD(datno); /* un-padd a record */ 
return(0); 


REFERENCE NUMBER - 32 
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NAME 

DT VLOUT- Variable record out function. (DT_CTREE.C) 
11Pe 

File 1/O 

DECLARATION 

UCOUNT DT VLOUT(dtsIn,dtsfp,dtefp,rcdlen) 
UCOUNT _ dtsln; /* unpacked record length */ 
DATOBJ *dtsfp; /* first field doda pointer */ 
DATOBJ *dtefp; /* end or last field doda pointer */ 
UCOUNT _ rcdlen; /* fixed length portion of record */ 
DESCRIPTION 


This function will pack a variable length record in preparation for it being written 
to disk. Note that the pack record is placed in an allocated memory block which 
should be freed when you are finished with the packed buffer. See add record 
logic below. 


RETURN 
Returns the length of the packed version on the record. 
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EXAMPLE 

Note how function is used here in the DT_ADREC function. 
COUNT DT_ADREC(datno) 

COUNT datno; /* data file number to add record to. */ 


{ 

VOID mbfree(); 

COUNT err; /* error flag */ 
UCOUNT DT VLOUT(; 
COUNT DT DOPAD(; 
UCOUNT vlen; 


DT DOPAD(datno); /* padd fields */ 


# ifdef UNIFRMAT 
unifrmat(datno); 
# endif 


if ((key + datno)-clstyp = =VAT_CLOSE) /* if variable length data */ 


vien=DT_VLOUT(dt_sin[datno],dt_sfp[datno],dt_efp[datno], 
(key + datno)-reclen); 


if (dt_vin= =NULL) 
{ 


printf("\n%cDtree addvrec datno = %d dt_vin = %x vlen = %d\n", 
13,datno,dt_vin,vlen); 

printf("dt_vin has a problem\n"); 

getchar‘(); 

} /* end debug */ 


if (LKISAM(ENABLE) | | ADDVREC(datno,dt_vin,vlen)) err =isam_ err; 
else { err=0; mbfree(dt_vin); } 


else 
{ 
if (LKISAM(ENABLE) | | ADDREC(datno,dt_sfp[datno]-fadr)) 


err=isam_err; 
else err =0; 


LKISAM(FREE); 
return(err); 
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REFERENCE NUMBER - 31 
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NAME 


DT_XTRCT- Extract a subset of the RELAT structure. (DT RELAT.C) 


TYPE 


Internal Structure Relationships 


DECLARATION 
DTTRELAT *DT_XTRCT(adr,elements, /* address of & no in base relate */ 


DTTRELAT *adr; 
COUNT elements; 
COUNT type; 
COUNT Ityp; 
COUNT Icnt; 
COUNT Isrt; 
COUNT rtyp; 
COUNT rent; 
COUNT rsrt; 
DTTRELAT *altadr: 
COUNT altelem; 
COUNT Itypchk; 
COUNT Icntchk; 
COUNT Isrtchk; 
COUNT rtypchk; 
COUNT rcntchk; 
COUNT rsrtchk; 
COUNT srtmod; 
COUNT *nofound; 
DESCRIPTION 


type, 


Ityp,lcnt,lsrt, 
rtyp,rcnt,rsrt, 


altadr, 
altelem, 


Itypchk,lcntchk,|srtchk, 
rtypchk,rcntchk,rsrtchk, 
srtmod,nofound) 


/* type of relate to extract */ 

/* left side type, count, & sort */ 

/* right side type, count & sort */ 
/* pointer to secondary relate */ 
/* num of elements in alt RELAT array */ 
/* alt set left side */ 

/* alt set right side */ 

/* sort mode and number found */ 
/* address of RELAT to extract from */ 

/* num of elements in RELAT array */ 

/* relationship type */ 

/* type of left structure */ 

/* left pointer count */ 

/* left structure alt sort */ 

/* type of right structure */ 

/* right pointer count */ 

/* right structure alt sort */ 

/* address of alt RELAT to compare against */ 
/* num of elements in alt RELAT array */ 
/* left type altcheck */ 

/* left counter alt check */ 

/* left sort alt check */ 

/* right type alt check */ 

/* right counter alt check */ 

/* right sort alt check */ 

/* sort mode */ 

/* no of matches found */ 


The extract function is used to make subsets of the any RELAT block. The ad- 
dress of the RELAT block, along with the number of relates in the block, are the 
first two parameters. The next seven parameters simply define the direct selec- 
tion criteria from this base RELAT block (such as relate type, left side type, left 
side count etc.). If an alt pointer is passed, this means that we are defining addi- 
tional criteria that must be met before a relate entry is selected and entered into 
our new subset. This criteria is basically that the selected entry must match an 
entry in an additional RELAT block based on the six chk flags that are sent as 
parameters to this function. 
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/* relate extract alt set compare types */ 

/* left side- Itypchk parm */ 

/* #define DTXTCLTL 1 left type of selected relate = left type in alt set */ 
/* #define DTIXTCLTR 2 left type of selected relate = right type in alt set */ 


/* left side- Icntchk parm */ 
/* #define DIXTCLCL 3 left count of selected relate = left count in altset */ 
/* #define DIXTCLCR 4 left count of selected relate = right count in altset */ 


/* left side- Isrtchk parm */ 
/* #define DTXTCLSL 5 left sort of selected relate = left sort in altset */ 
/* #define DTIXTCLSR 6 left sort of selected relate = right sort in altset */ 


/* right side- */ 

/* right side- rtypchk parm */ 

/* #define DIXTCRTL 7 right type of selected relate = left type in altset */ 
/* #define DIXTCRTR 8 right type of selected relate = right type in altset */ 


/* right side- rentchk parm */ 
/* #define DTIXTCRCL 9 right count of selected relate = left count in altset */ 
/* #define DTIXTCRCR 10 right count of selected relate = right count in altset */ 


/* right side- rsrtchk parm */ 
/* #define DTIXTCRSL 11 right sort of selected relate = left sort in altset */ 
/* #define DTIXTCRSR 12 right sort of selected relate = right sort in altset */ 


RETURN 
NORMAL RETURN 
Returns a pointer to the subset. 


ERROR RETURN 
Symbolic 
Value Constant Explanation 
0x4501 ERR_4501 Could not allocate extract space 
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EXAMPLE 

if (!(rptr=DT_XTRCT(DTGRELAT,DTNRELAT, /* ptr to RELAT & no of elements */ 
DTXTCNUL, /* relationship type */ 
DTKIMAGE,c,DTXTCNUL, /* IMAGE type and image count */ 
DTKFIELD,DTXTCNUL,DTXTCNUL,  /* FIELD type */ 
((DTTRELAT *)(NULL)),DTXTCNUL,  /* alt RELAT adr & no elements */ 
DTXTCNUL,DTXTCNUL,DTXTCNUL, //* left side alt criteria */ 
DTXTCNUL,DTXTCNUL,DTXTCNUL, //* right side alt criteria */ 
DTQSRTAC, &nofound)) && uerr_ cod) /* sort mode and num extracted */ 


printf("extract err\n"); getchar(); 
return(ERR_ 4005); /* memory allocation error */ 


} 
REFERENCE NUMBER - 45 
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NAME 
DT ZROIT- Zero out a field give only the DODA symbol name. (DT WDODA.C) 


TYPE 
Data Management 


DECLARATION 
COUNT DT ZROIT(dsymb) 
TEAT *dsymb; /* destination symbol */ 


DESCRIPTION 

This function will zero out a field given the symbolic name for the field in the 
DODA. This function is only set to handle doubles at this time, but may be used 
as an example of accessing the DODA. 


RETURN 
Returns a 1 if failed. 
returns a zero if successful 


EXAMPLE 
DT_ZROIT("mybalance"); 


REFERENCE NUMBER - 5D 
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NAME | 

DTPCALCS- Parse the CALCS Ability definition. (DTPCALCS.C) 
TYPE 

Ability Parsing 

DECLARATION 

COUNT DTPCALCS(kwptr, parsebuf,len) 

DTTKEYWD *kwotr; /* ptrs to keyword structure */ 
FAST TEXT *parsebuf; /* pointer to temp parsing buffer */ 
COUNT len; /* length of temp parsing buffer */ 
DESCRIPTION 


This function interprets the CALCS keyword syntax from the temporary parsing 
buffer and initializes a structure of DTTCALCS type with the definition. 


RETURN 
NORMAL RETURN 
successful parse returns zero 


ERROR RETURN 
Symbolic 
Value Constant Explanation 
Ox821 ERR_821 Space allocation error 
Ox822 ERR 822 _ Expression too long for postfix conversion 
- change DIMXWORK in DTPCALCS.C 


SEE ALSO 
DTTCALCS - typedef definition in Ability typdef section. 


REFERENCE NUMBER - 82 
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NAME , 

DTPCONST- Parse the CONST Ability definition. (OTPCONST.C) 
TYPE 

Ability Parsing 

DECLARATION 

COUNT DTPCONST (kwptr, parsebuf,len) 

DTTKEYWD *kwotr; /* ptrs to keyword structure */ 
FAST TEXT *parsebuf; /* pointer to temp parsing buffer */ 
COUNT len; /* length of temp parsing buffer */ 
DESCRIPTION 


This function interprets the CONST keyword syntax from the temporary parsing 
buffer and initializes a structure of DTTCONST type which contains the defini- 
tion. The CONST structure has had all of its fields defined by the IMAGE parse, 
except the output attribute. This keyword is supplied by this attribute’s definition. 


ABILITY SYNTAX - 
CONST(master) 

1 RI 

“~ *..... output attribute. 
mae: constant number. 
ABILITY TYPEDEF - 


typedef struct { 
TEA 


*string; /* pointer to constant text */ 
COUNT len; /* length displayed on screen */ 
COUNT outatr[DT MXOAT]; /* output attribute */ 
COUNT col; /* column number for display */ 
COUNT row; /* row number for display */ 


} DTTCONST; 
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RETURN 
NORMAL RETURN 
successful parse returns zero 


ERROR RETURN 
Symbolic 

Value Constant Explanation 
0x4601 ERR_4601 Image number for constant not defined. 
Ox4602 ERR 4602 Token not a valid constant or attribute. 
0x4603 ERR 4603 Invalid output attribute. 
0x4604 ERR_4604 Attribute does not refer to any constant. 
Ox4605 ERR_4605 Could not allocate space for extract. 


SEE ALSO 
DTTCONST - typedef definition in Ability typdef section. 


REFERENCE NUMBER - 46 
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NAME | 

DTPDFALT- Parse the DFALT Ability definition. (DTPDFALT.C) 
TYPE 

Ability Parsing 

DECLARATION 

COUNT DTPDFALT (kwptr, parsebuf,len) 

DTTKEYWD *kwoptr: /* ptrs to keyword structure */ 
FAST TEXT *parsebuf; /* pointer to temp parsing buffer */ 
COUNT len; /* length of temp parsing buffer */ 
DESCRIPTION 


This function interprets the DFALT keyword syntax from the temporary parsing 
buffer and initializes a structure of DTTDFALT type with the definition. An entry is 
also made into the relate structure to link this default definition to the field that it 
pertains to. 


ABILITY SYNTAX - 


DEFAULTS (master) 

ies Symbol Name Type of defaults Defaults value */ 
fiel name TAB Reno Office 
cou_Office INIT SYSDATE 
cou_Office TAB SYSTIME 

/* Valid DFALT type symbols */ 
TAB - default when auto dup key is hit 
INIT - default at initialization time 
DUPTAB - auto dup when auto dup key is hit 
DUPINIT - auto dup at initialization time 


ABILITY TYPEDEF - 


typedef struct { 


COUNT num; /* default number */ 

COUNT dftyp; /* type of default */ 

TEXT * dftxt; /* pointer to default text */ 
} DTTDFALT; 
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RETURN 
NORMAL RETURN 
successful parse returns zero 


ERROR RETURN 
Symbolic 
Value Constant Explanation 
0x7701 ERR_7701 Could not allocate DFALT structure space. 
Ox7702 ERR_7702 Could not allocate memory for DFALT text. 
0x7703 ERR_7703 Could not allocate DFALT’s RELAT space. 
Ox7704 ERR_7704 Error-Default type must follow field name. 


SEE ALSO 
DTTDFALT typedef definition in Ability typdef section. 


REFERENCE NUMBER - 77 
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NAME 

DTPEDITS- Parse the EDITS Ability definition. (ODTPEDITS.C) 

TYPE 

Ability Parsing 

DECLARATION 

COUNT DTPEDITS(kwptr, parsebuf,len) 

DTTKEYWD *kwoptr; /* ptrs to keyword structure */ 
FAST TEXT *parsebuf; /* pointer to temp parsing buffer */ 
COUNT | len; /* length of temp parsing buffer */ 
DESCRIPTION 


This function interprets the EDITS keyword syntax from a d-tree script and initial- 
izes a structure of DITEDITS type with the definition. 


ABILITY SYNTAX - 


EDITS(master) 
Must Enter County Code cou_cod MAND FILL 


ABILITY TYPEDEF - 
typedef struct { 


COUNT edttyp; /* type of edit */ 
TEXT *edttxt; /* pointer to edit message text */ 
TEXT *addtxt; /* additional text */ 

} DTTEDITS: 
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RETURN 


NORMAL RETURN 
successful parse returns zero 


ERROR RETURN 
Symbolic 


Value 

Ox6601 
Ox6602 
0x6603 
Ox6604 
Ox6605 
Ox6606 
Ox6607 
Ox6608 
Ox6609 


SEE ALSO 


Constant 
ERR 6601 
ERR_ 6602 
ERR_6603 
ERR_6604 
ERR_6605 
ERR_ 6606 
ERR_6607 
ERR_ 6608 
ERR_ 6609 


Explanation 

Could not allocate EDITS structure. 

Could not allocate memory for EDITS text. 

Could not allocate EDITS’s RELAT memory. 

Edit type must follow edit text. 

Edit Type must follow field name. 

Must enter message text. 

Field not found on associated image. 

DUPKEY edit must have key no or name. 
DUPKEY key symbol length to short. 

for example: key symbol = "ky" and the key number it 
represents is "100". The "ky" is only 2 digits, the 
"100" is 3 digits. Due to memory allocation this is 
invalid. 


DTTEDITS - typedef definition in Ability typdef section. 
REFERENCE NUMBER - 66 
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NAME 

DTPFIELD- Parse the FIELD Ability definition. (ODTPFIELD.C) 

TYPE 

Ability Parsing 

DECLARATION 

COUNT DTPFIELD(kwptr, parsebuf,len) | 

DTTKEYWD *kwoptr; /* ptrs to keyword structure */ 
FAST TEXT *parsebuf; /* pointer to temp parsing buffer */ 
COUNT len; /* length of temp parsing buffer */ 
DESCRIPTION 


This function interprets the FIELD keyword syntax from the temporary parsing 
buffer and initializes a structure of DTTFIELD type with the definition. 


ABILITY SYNTAX - 

FIELD(master) 

/* Symbol Name Input Attribute Output Attribute Input Order Special */ 
cou_cod ALLCAPS Rl 1 user function 


ABILITY TYPEDEF - 
typedef struct { 


DATOBJ *fdoda; /* pointer to doda */ 
COUNT fdodano: /* doda number */ 


COUNT len; /* length displayed on screen */ 
COUNT inpatr; /* input attribute */ 
COUNT outatr[DT_ MXOAT]; /* output attribute */ 
COUNT col; /* column number for display */ 
COUNT row; /* row number for display */ 
COUNT dec; /* decimal positions */ 
DT FPTR _ funcptr; /* special function pointer */ 

} DITRIELD: 
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RETURN 


NORMAL RETURN 
successful parse returns zero 


ERROR RETURN 


Value 

0x1001 
0x1002 
0x1003 
0x1004 
0x1005 
0x1006 
0x1007 
0x1008 
0x1009 
0x1010 


SEE ALSO 


Symbolic 
Constant 
ERR_1001 
ERR_1002 
ERR_1003 
ERR_1004 
ERR_1005 
ERR_1006 
ERR_1007 
ERR _ 1008 
ERR_ 1009 
ERR 1010 


Explanation 

Symbolic Name Not Found In DODA. 
Invalid Input Attribute. 

Invalid Output Attribute. 

Syntax Error Found. 

Pointer not pointing to a valid field. 
Could not Allocate Parse space. 

No Image with same number found. 

No Field to Image relationships. 
Relationship pointer Incremented to Far. 
Invalid user defined function or Invalid field symbol 
name. 


DITTFIELD - typedef definition in Ability typdef section. 
REFERENCE NUMBER - 10 
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NAME 

DTPHELPP- Parse the HELPP Ability definition. (DTPHELPP.C) 
TYPE 

Ability Parsing 

DECLARATION 

COUNT DTPHELPP(kwptr, parsebuf,len) 

DTTKEYWD *kwotr; /* ptrs to keyword structure */ 
FAST TEXT *parsebuf; /* pointer to temp parsing buffer */ 
COUNT len; /* length of temp parsing buffer */ 
DESCRIPTION 


This function interprets the HELPP keyword syntax from the temporary parsing 
buffer and initializes a structure of DTTHELPP type with the definition. 


RETURN 
NORMAL RETURN 
Returns a zero if no errors where found. 


ERROR RETURN 
Symbolic 

Value Constant Explanation 

0x841 ERR 841. DTPHELPP-Space Allocation Error 

0x842 ERR 842 DTPHELPP-Syntax Error. Help text or token must 
be defined before fields 

0x843. ERR 843. DTPHELPP-Syntax Error. USES SFL not define 
correctly 


SEE ALSO 
DTTHELPP - typedef definition in Ability typdef section. 


REFERENCE NUMBER - 84 
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NAME 

DTPIFILS- Parse the IFILS Ability definition. (DTPI FILS.C) 

TYPE 

Ability Parsing 

DECLARATION 

COUNT DTPIFILS(kwptr,parsebuf,len) 

DTTKEYWD *kwotr; /* ptrs to keyword structure */ 
FAST TEXT *parsebuf; /* pointer to temp parsing buffer */ 
COUNT len; /* length of temp parsing buffer */ 
DESCRIPTION 


This function interprets the IFILS keyword syntax from the temporary parsing 
buffer and initializes a structure of DTTIFILS type with the definition. 


ABILITY SYNTAX - 


IFILS 
FILE NAME ray.dta 


KEY NAME rayidx 
KEY FIELDS cou_cod cou_name 


KEY NAME billidx 
KEY_FIELDS cou_name DUPS OK 


FIRST_FIELD cou_cod 
LAST_FIELD cou type - 
FIRST_VLEN cou_name 
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typedef struct iseg { 

COUNT soffset, 
slength, 
segmode; 

} ISEG; 


typedef struct iidx { 

COUNT ikeylen, 
ikeytyp, 
ikeydup, 
inulkey, 
iempchr, 
inumseg; 

ISEG —*seg; 

ToAT *ridxnam; 

} MDX; | 


typedef struct ifil { 
TEXT *pfilnam; 
COUNT dfilno; 
UCOUNT _ dreclen; 
UCOUNT _ dxtdsiz: 
COUNT dfilmod; 
COUNT dnumidx; 
UCOUNT _ ixtdsiz: 
COUNT ifilmod: 


IDX “ix: 
TEAL *rfstfld; 
TEXT *ristfld; 
COUNT tfilno; 
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/* segment offset */ 
/* segment length */ 
/* segment mode */ 


/* key length */ 

/* key type */ 

/* duplicate flag */ 

/* null key flag */ 

/* empty character */ 

/* number of segments */ 
/* segment information */ 
/* r-tree symbolic name */ 


/* file name (W/o ext) */ 
/* data file number */ 
/* data record length */ 
/* data file ext size */ 
/* data file mode */ 

/* number of indices */ 
/* index file ext size */ 
/* index file mode */ 

/* index information */ 
/* r-tree 1st fld name */ 
/* r-tree last fld name */ 


/* temporary file number*/ 


DTPIFILS 
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RETURN 


NORMAL RETURN 
successful parse returns zero 


ERROR RETURN 


Value 
Ox801 
Ox802 
0x803 
0x804 
0x805 
Ox806 
0x807 
0x808 


0x809 


SEE ALSO 


Symbolic 
Constant 
ERR_ 801 
ERR_802 
ERR _ 803 
ERR 804 
ERR 805 
ERR 806 
ERR_ 807 
ERR _ 808 


ERR_809 


Explanation 

Unable to allocate IFILS structures. 

Unable to allocate IIDXS structures. 

Unable to allocate ISEGS structures. 

Unable to allocate space for text info. 

Syntax error-Must have IFILS symbol. 

Field defined as key segment not in DODA. 
Field defined first or last field not in DODA. 
Field defined as first variable length field is not 
in DODA. 

Must define KEY_NAME before defining DUPS OK. 


DTTIFILS - typedef definition in Ability typdef section. 
REFERENCE NUMBER - 80 
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NAME 

DTPIMAGE- Parse the IMAGE Ability definition. (DTPIMAGE.C) 
TYPE 

Ability Parsing 

DECLARATION 

COUNT DTPIMAGE (kwptr, parsebuf,len) 

DTTKEYWD *kwptr; /* ptrs to keyword structure */ 
FAST TEXT *parsebuf; /* pointer to temp parsing buffer */ 
COUNT len; /* length of temp parsing buffer */ 
DESCRIPTION 


This function interprets the IMAGE keyword syntax from the temporary parsing 
buffer and initializes a structure of DITIMAGE type with the definition. 


ABILITY SYNTAX - 


IMAGE (heading) 
{LSTFLD_ ADVANCE} 
{FRSFLD BACKUP} 
{INPUT ADVANCE = 2} 


@DATE 
@TIME 


Number: 


Name: 
Code: 
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typedef struct { 


COUNT num; /* image number */ 
COUNT cls; /* clear screen flag */ 
COUNT Ister; /* exit on last field carride return */ 
COUNT fstbu; /* exit on first field backup */ 
COUNT inpno; /* if this many fields have been entered then exit */ 
COUNT topcol; /* Top left corner column for display */ 
COUNT toprow; /* Top left corner row for display */ 
COUNT basecol; /* Top left corner column from parse */ 
COUNT baserow;  /* Top left corner row from parse */ 
COUNT noofvar; /* number of variable fields */ 
COUNT noofcon; /* number of constant fields */ 
COUNT fstrow; /* first row */ 
COUNT Istrow; /* last row */ 
COUNT lftcol; /* left most column */ 
COUNT ritcol; /* right most column */ 
TEXT *varptr; /* first variable relate ptr */ 
TEXT *conptr; /* first constant relate ptr */ 

} DTTIMAGE; 

RETURN 


NORMAL RETURN 
successful parse returns zero 


ERROR RETURN 
Symbolic 
Value Constant 
0x1601 
0x1602 
0x1603 
0x1604 


0x1605 


SEE ALSO 
DTTIMAGE - typedef definition in Ability typdef section. 


REFERENCE NUMBER - 16 


Explanation 

ERR_1601 Could not Allocate Parse space. 

ERR_1602 Invalid Optional Feature. 

ERR_1603 Could not allocate space for DODA. 

ERR_1604 Could not allocate space for DODA symbolic names text. 
ERR_1605 INPUT ADVANCE option invalid. 
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NAME 

DTPKEYBD- Parse the KEYBD Ability definition. (DTPKEYBD.C) 
TYPE 

Ability Parsing 

DECLARATION 

COUNT DTPKEYBD(kwptr, parsebuf,len) 

DTTKEYWD *kwotr; /* ptrs to keyword structure */ 
FAST TEXT *parsebuf; /* pointer to temp parsing buffer */ 
COUNT len; /* length of temp parsing buffer */ 
DESCRIPTION 


This function interprets the KEYBD keyword syntax from the temporary parsing 
buffer and initializes a structure of DITTKEYBD type with the definition. It is nor- 
mally called by the DT_KEYBD routine which loads the definition into the pars- 
ing buffer. 


ABILITY SYNTAX - 


TERMINAL (vt100) 

ESC 27 27 CR 13 BU 8 DC 27 91 67 IC 27 91 68 DW 27 91 66 
UP 27 91 65 PD 2 PUG LF 27 79 82 RT 27 79 83 HM 27 79 80 
EN 27 79 81 AD 9F1 27 49 F2 27 50 F3 27 51 F4 27 52 

F5 27 53 F6 27 54 F7 27 55 F8 27 56 F9 27 57 F10 27 58 
CTLA 1 F113LOC 0 2791 12059 121 72 CLS 279150 74 
EOL 27 91 75 UL 27 91 52 109 RI 27 91 55 109 NA 27 91 48 109 
PS 2 HL 27 61 LOTUS 27 91 55 109 


ABILITY TYPEDEF - 


typedef struct { 

COUNT terminal; /* terminal id */ 

COUNT retcode; /* what to return if input matches*/ 

COUNT frschar; /* first char of key sequence */ 

COUNT noofchar; /* no of additional char in sequence*/ 

TEXT addchar[DT MXSEQ]; __/* additional chrcters in seqence */ 
} DTTKEYBD: 
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RETURN 
NORMAL RETURN 
successful parse returns zero 


ERROR RETURN 
Symbolic 
Value Constant Explanation 
0x7101 ERR_7101 Could not allocate space for key seq. 
0x7102 ERR_7102 Syntax error in termcap definition. 
0x7103_ ERR_7103 DT_MXSEQ not large enough in DT _TYPDF.H. 


SEE ALSO 
DT TKEYBD - typedef definition in Ability typdef section. 


REFERENCE NUMBER - 71 
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NAME 
DTPKEYST- Keyboard definition sort function. Sort the KEYBD memory block. 
(DTPKEYBD.C) 


TYPE 
Ability Parsing 


DECLARATION 
COUNT  DTPKEYST() 


DESCRIPTION 
This function sorts the keyboard structure by terminal, first key, no of gets. 


Explanation- here we first sort the terminal definition in terminal, first key in spe- 
cial sequence, then no of extra getchar’s order. We then loop thru the special 
keys array and map the return code into the keymap array. If any negative num- 
bers are entered, they are mapped above 127 in the keymap array. If we find a 
sequence that needs more than one getchar or we find more than one se- 
quence that start with the same character, we store the offset + 1000 of the first 
special sequence in the keymap. When this key is entered we can tell that we 
need to go to the special definition because the value in the keymap is > 1000. 
By subtracting 1000 from any value found over 1000 we get the occurrence 
number of the first special keystroke with this first character. 


RETURN 
Always returns a zero. 


EXAMPLE 
DTPKEYST(): 


REFERENCE NUMBER - 74 
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NAME 

DTPMAPIT- Parse the MAPIT Ability definition. (DTPMAPIT.C) 
TYPE 

Ability Parsing 

DECLARATION 

COUNT — DTPMAPIT(kwptr,parsebuf,len) 

DTTKEYWD *kwptr; /* ptrs to keyword structure */ 
FAST TEXT *parsebuf; /* pointer to temp parsing buffer */ 
COUNT len; /* length of temp parsing buffer */ 
DESCRIPTION 


This function interprets the MAPIT keyword syntax from the temporary parsing 
buffer and initializes a structure of DTTMAPIT type with the definition. This 
ABILITY does not have an associated typdef for it simply makes entries into the 
relate structure to link the two fields. 


ABILITY SYNTAX - 


MAP (name) 
/* source field desination field length */ 
acctnum cou_cod 3 


acctnam cou_name 
acctcmt cou_ Office 


RETURN 
NORMAL RETURN 
successful parse returns zero 


ERROR RETURN 
Symbolic 
Value Constant Explanation 
Ox951 ERR 951 Must have an even number of flds defined. 
Ox952 ERR_952 Could not allocate space for MAP relates. 
Ox953_ ERR 953 _ Field symbol name not found in DODA. 
Ox954 ERR_954 Copy length longer than child field. 
Ox955 ERR_955 Invalid MAP type. 
Ox961 ERR 961 Could not allocate space for extract. 


SEE ALSO 
DTTMAPIT - typedef definition in Ability typdef section. 


REFERENCE NUMBER - 95 
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NAME 

DTPMENUS- Parse the MENUS Ability definition. (DTPMENUS.C) 
TYPE 

Ability Parsing 

DECLARATION 

COUNT DTPMENUS (kwptr, parsebuf,len) 

DTTKEYWD *kwotr; /* ptrs to keyword structure */ 
FAST TEXT *parsebuf; /* pointer to temp parsing buffer */ 
COUNT len; /* length of temp parsing buffer */ 
DESCRIPTION 


_ This function interprets the MENUS keyword syntax from the temporary parsing 
buffer and initializes a structure of DTTMENUS type with the definition. 


ABILITY SYNTAX - 


MENU (master) 

USES _IMAGE(menu) 

/* Call Criteria Type of Call Call Value */ 
option=1 CURSOR =name EXECL my_program 
option=1 CURSOR =name SYSTEM my_program 
option=1 CURSOR =name CALL my_function 
option=1 CURSOR =name RETURN 1 


ABILITY TYPEDEF - 


typedef struct { 


COUNT num; /* menu number */ 
COUNT imageno; _ /* image number */ 
COUNT inputfld; /* input field no */ 
COUNT cursfld; /* last field that cursor was on */ 
COUNT comptyp; /* compare type */ 
COUNT Calltyp; /* type of menu call */ 
TEXT *comptxt; /* compare input field text */ 
TEAT *calltxt; /* call text */ 
} DTTMENUS; - 
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RETURN 


NORMAL RETURN 
successful parse returns zero 


ERROR RE 


Value 
Ox5E1 
Ox5E2 
Ox5E3 
Ox5E4 
OxSES 
Ox5E6 
Ox5E7 


SEE ALSO 


TURN 


Symbolic 
Constant 
ERR_5E1 
ERA .SE2 
ERR SES 
ERR_5E4 
ERR SES 
ERR_5E6 
EA. SEZ 


Explanation | 

Space Allocation Error. 

Menu Call type must follow input criteria. 
Must enter Compare Criteria. 

Must enter Call Text. 

CURSOR = symbol..symbol not in DODA. 
Field compare symbol not in DODA. 
Must define USES IMAGE first. 


DTTMENUS - typedef definition in Ability typdef section. 
REFERENCE NUMBER - 5E 
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NAME 

DTPPRMPT- Parse the PRMPT Ability definition. (OTPPRMPT.C) 
TYPE | 

Ability Parsing 

DECLARATION 

COUNT DTPPRMPT(kwptr, parsebuf,len) 

DTTKEYWD *kwotr; /* ptrs to keyword structure */ 
FAST TEXT *parsebuf; /* pointer to temp parsing buffer */ 
COUNT len; /* length of temp parsing buffer */ 
DESCRIPTION 


This function interprets the PRMPT keyword syntax from the temporary parsing 
buffer and initializes a structure of DTTPRMPT type with the definition. 


ABILITY SYNTAX - 
PROMPT (master) 


USES _IMAGE(prompt) 
/* key symbol name = scannname_ fields for target prefix */ 


C_ Num master cou_cod 
C Nam master cou_name ray 
NONE master option 


ABILITY TYPEDEF - 


typedef struct { 


COUNT num; /* prompt number */ 
COUNT imageno; _ /* image number */ 
COUNT scanno; /* associated scann number */ 
TEXT *string; /* prefix */ 
} DTTPRMPT; 
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RETURN 
NORMAL RETURN 
successful parse retums zero 


ERROR RETURN 
Symbolic 

Value Constant Explanation 
0x3801 ERR_3801 Could not allocate space for prompt. 
Ox3802 ERR 3802 Could not allocate space for relations. 
0x3803 ERR_3803 Invalid keyword-define USES IMAGE(?). 
0x3804 ERR_3804 Image number/name not defined correctly. 
Ox3805 ERR_3805 Key symbol name not in ISAM definition. 
Ox3806 ERR_3806 Field symbol name not found in doda. 
0x3807 ERR_3807 FIELD defined not on IMAGE defined. 
Ox3808 ERR 3808 Could not allocate space for prefix. 
0x3809 ERR_3809 Scann Number not defined. 
0x3810 ERR_3810 Scann Number must be defined before target fields. 


SEE ALSO 
DTTPRMPT - typedef definition in Ability typdef section. 


REFERENCE NUMBER - 38 
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NAME 

DTPRTREE- Parse the RTREE Ability definition. (ODTPRTREE.C) 
TYPE 

Ability Parsing 

DECLARATION 

COUNT DTPRTREE(kwptr, parsebuf,len) 

DTTKEYWD *kwotr; /* ptrs to keyword structure */ 
FAST TEXT *parsebuf; /* pointer to temp parsing buffer */ 
COUNT len; /* length of temp parsing buffer */ 
DESCRIPTION 


This function interprets the RTREE keyword syntax from the temporary parsing 
buffer and initializes a structure of DITRTREE type with the definition. 


ABILITY SYNTAX - 


RTREE(my_report) 
USES _IMAGE(my_report) 
USES SCRIPT(ex_rtree.rts) 
REPORT PROGRAM(ex_rtree.rts) 
CALL_TYPE(MEMORY) 
CALL_TYPE(EXECL) 
CALL _TYPE(SYSTEM) 


/* r-tree criteria Substitute */ 
/* keyword fields String */ 
SEARCH NONE FILE "ARAY.DTA" ALL 


option1 FILE "ARAY.DTA" USING KEY KEY1 [ "{option1 }" 


SELECT NONE ALL 
options (balanced.00) 


VIRTUAL NONE dev INT2 21 
option6 dev INT2 2 "{option6 }" 


SORT NONE LEAVE OUT 
option7 NO MOD "{option7}" 
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ABILITY TYPEDEF - 


typedef struct { 


COUNT num; /* rtree definition number */ 
COUNT imageno; /* image number */ 
COUNT type; /* interface type */ 
COUNT rtkeywd; /* rtree keyword reference number */ 
TEXT *script; /* base r-tree script name */ 
TEAE *string; /* substitute string */ 
TEAL *program; * program to run */ 
} DTTRTREE; 
RETURN 
NORMAL RETURN 


successful parse returns zero 


ERROR RETURN 


Ox6F 1 
Ox6F2 
Ox6F3 


Ox6F4 


Ox6F5 
Ox6F6 
Ox6F7 
Ox6F8 
Ox6F9 


Ox6FA 
Ox6FB 


SEE ALSO 


Value 

ERR 6F1 
ERR_6F2 
ERR_6F3 


ERR_6F4 


ERR_6F5 
ERR 6F6 
ERR 6F7 
ERR 6F8 
ERR 6F9 


ERR_6FA 
ERR _6FB 


Symbolic 

Constant Explanation 

Could not allocate space for rtree definition. 
Could not allocate space for relations. 

Invalid definition keyword 

-define USES _IMAGE(?) or 

-define USES SCRIPT(?). 

Must define USES_IMAGE and USES SCRIPT properly. 
Check for valid image number or that you have not 
defined both keywords properly. 

Invalid r-tree keyword. 

Field symbol name not found in doda. 

FIELD defined not on IMAGE defined. 

Could not allocate space for text. 

One of the following keyword has a syntax error: 
USES IMAGE(??) 

USES _SCRIPT(??) 

REPORT_PROGRAM(??) 

CALL PYPE?7) */ 

Must define substitution text. 

Invalid Call Type. 


DTTRTREE - typedef definition in Ability typdef section. 
REFERENCE NUMBER - 6F 
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NAME 

DTPSCANN- Parse the SCANN Ability definition. (OTPSCANN.C) 
TYFE 

Ability Parsing 

DECLARATION 

COUNT DTPSCANN (kwptr, parsebuf,len) 

DTTKEYWD *kwotr; /* ptrs to keyword structure */ 
FAST TEXT *parsebuf; /* pointer to temp parsing buffer */ 
COUNT len; /* length of temp parsing buffer */ 
DESCRIPTION 


This function interprets the SCANN keyword syntax from the temporary parsing 
buffer and initializes a structure of DITTSCANN type with the definition. 


ABILITY SYNTAX - 

SCAN (master) 
{IMAGE _OUT =heading} 
{IMAGE ROL =rollpart} 
{IMAGE_INP = heading} 
{USE SETS =2} 

ABILITY TYPEDEF - 


typedef struct { 


COUNT num; /* scan number */ 

COUNT imgout; /* header image number */ 
COUNT imgrol; /* rolling image number */ 
COUNT imginp; /* input image number */ 
COUNT useset; /* use c-tree FRSSET logic */ 


/* values 0 = do not use sets */ 

/* -1 = use provided target sig len */ 

/* >0 = the sig length to use for sets*/ 
} DITSCANN: 


Py at a TSE Rn So SPE SO eo oe a ee AE NETS SE NS OnE eae ere a a ee ae 
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RETURN 
NORMAL RETURN 
successful parse returns zero 


ERROR RETURN 
Symbolic 

Value Constant Explanation 
0x3901 ERR_3901 Could not allocate space for SCANN. 
0x3902 ERR_3902 Invalid SCANN option defined. 
0x3903 ERR_3903 IMAGE_OUT image no not a defined IMAGE. 
0x3904 ERR_3904 Must have valid IMAGE ROL imageno. 
0x3905 ERR_3905 Must have valid IMAGE_INP imageno. 


SEE ALSO 
DTTSCANN - typedef definition in Ability typdef section. 


REFERENCE NUMBER - 39 
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NAME 

DTPSUBFL- Parse the SUBFL Ability definition. (DTPSUBFL.C) 
TYPE 

Ability Parsing 

DECLARATION 

COUNT DTPSUBFL(kwptr, parsebuf,len) 

DTTKEYWD *kwptr; /* ptrs to keyword structure */ 
FAST TEXT *parsebuf; /* pointer to temp parsing buffer */ 
COUNT len; /* length of temp parsing buffer */ 
DESCRIPTION 


This function interprets the SUBFL keyword syntax from the temporary parsing 
buffer and initializes a structure of DITSUBFL type with the definition. 


ABILITY SYNTAX - 
SUBFILE(master) 
SFL_IMAGE (rollpart) 
SFL_TITLE(title) 


SFL_RECORDS(40) 
SFL_LINES(18) 


SFL_ATTR 

NO ROLL CR 

SFL_TARGET 

/* key symbol name fields for target prefix */ 
C Num targetfield(12) 01 


SFL_BOUNDARY 
/* doda first field doda last field */ 
dodafield1 dodafield2 


SFL_MAP 

/* parent field child field length */ 
cou_cod cou_name 11 
SFL_SEQ cou_seq 


SFL_MUSTHAVE 
cou_cod cou_name 
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ABILITY TYPEDEF - 

typedef struct { 
TEXT *sptr; /* sfl memory block */ 
TEXT target[MAXLEN]; /* target used to load sfl */ 


DITSUBSB *ctlptr; 
DITTSUBSB *sptr; 


} DTTSUBFL; 


COUNT tarsigIn; /* target sig length */ 
COUNT noofrcds; /* number of records in sfl */ 
COUNT currcd; /* current sfl record */ 
COUNT currow; /* current sfl row */ 

} DTTSUBSB; 

typedef struct { 
COUNT num; /* subfile number */ 
COUNT imageno; /* image number */ 
COUNT title; /* title image number */ 
TEXT * prefix; /* target prefix */ 
COUNT maxrcds; /* max number of records for subfile */ 
COUNT Sfllines; /* total number of display lines for sfl */ 
COUNT Sstartdoda; /* starting doda occurrence number */ 
COUNT enddoda; /* ending doda occurrence number */ 
COUNT keyno; /* keyno associated with this subfile */ 
COUNT noofsfls; /* number of sfl ptrs in memory ctl block*/ 
COUNT sflatr; /* subfile attributes */ 


/* sfl memory control block */ 
/* current block */ 


——-- _—_—_—_—_———— ee eSeSSSSSFFFFMSSeseseseseSsSeSsSeseseseseOCCCt”t 
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RETURN 


NORMAL RETURN 
successful parse returns zero 


ERROR RETURN 


Value 

0x5501 
0x5502 
0x5503 
0x5504 


Ox5505 
0x5506 
Ox5507 
0x5508 
Ox5509 
Ox5510 
Ox5511 
OxS5 2 
0x5513 
Ox5514 
OxX55 15 
UXOS 15 
teeea rs 
Ox5518 
0Ox5519 
0x5520 
Ox5521 


SEE ALSO 


Symbolic 
Constant 
ERR_5501 
ERR 5502 
ERR 5503 
ERR_5504 


ERR 5505 
ERR 5506 
ERR 5507 
ERR 5508 
ERR 5509 
ERR 5510 
ERR 5511 
ERR 5512 
ERR 5513 
ERR 5514 
ERR 5515 
ERR 5516 
ERR 5517 
ERR 5518 
ERR 5519 
ERR_5520 
ERR 5521 


Explanation 

Could not allocate space for subfile definition. 

Could not allocate space for relationships. 

Parse is expecting to see a subfile keyword-syntax error. 
Parse cannot determine what sfl keyword is being parsed- 
syntax error. 

SFL_IMAGE number/name not defined correctly. 
Invalid Number for MAX_RECORDS value. 

Invalid Number for SFL_LINES value. 

SFL_IMAGE must be define before SFL_TARGET. 
SFL_RECORDS must be define before SFL_TARGET. 
SFL_LINES must be define before SFL_TARGET. 
Key symbol name not in ISAM definition. 

Syntax error-looking for Key symbol name. 

Field symbol name not found in doda. 

Only one SFL_TARGET definition allowed. 

SFL_MAP Field symbol name not found in doda. 
SFL_MAP length longer than child field. 
SFL_TARGET must define target field or prefix. 
SFL_MUSTHAVE field not found in DODA. 
SFL_BOUNDARY field not found in DODA. 
SFL_PARENT-sfl parent no defined. 
SFL_ATTR-invalid subfile attribute. 


DTTSUBFL - typedef definition in Ability typdef section. 
REFERENCE NUMBER - 55 
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ADVANCED CONCEPTS 
Adding to d-tree 


This chapter lists the steps necessary to build on the base of definitions 
provided with d-tree. 


9.1 Adding a New Ability 


As you have already seen, d-tree is made up of a variety of abilities. d-tree was 
designed to allow the user to define their own abilities. There are a number of 
steps necessary in order to add a new ability to d-tree. In this discussion we will 
state each necessary step. Each step will then be illustrated , as we actually add 
a new ability to d-tree. 


e 1) The Idea - First a need (or an ability) must be conceptualized by the 
developer. In other words we must start with an idea for an ability that 
we want to add to d-tree. For the illustration, let’s add an ability for 
"communications". Here’s the conceptual view of our need (or ability): 
We would like to have a function we can call from our programs to 
perform communications with another computer. The definitions of 
where, how, and what to communicate need to be defined as a 
"generic" so that we can use this function in a variety of applications. 
Rather than "hard coding" any specifics to the communication function, 
we will store the “specifics” in a structure. The communication function 
will be passed a pointer to this structure, where it can get the 
requirements to perform that specific communication. By simply 
changing the data in the structure, we can change the communications 
definition. In order to initialize this structure easily with “our specific" 
comminication information, we will use a "script" interface. The script 
provides an easy manner by which the user can define the 
communications for a specific application. Parsing this script will 
initialize the "communications structure". With this definition in memory, 
the "communications function" can be called to perform the task. The 
following steps will pull this all together. 


e 2) Reference Word - For coding consistency, we assign a five (5) 
letter reference word to our ability. In this case we'll use "COMUN". 
This is used as we assign variable names and definition names to 
d-tree. (i.e. IMAGE, FIELD, SCANN, and now COMUN) 
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@ 3) "dt_defin.h" - Next we must assign a reference number for our 
ability to d-tree. This is done by going into the file "dt_defin.h". Look 
for the #define DTKLAST. Insert a line above the #define DTKLAST 


defined for DIKLAST. Once we have done this we must increment 
DTKLAST by one (1). See illustration below: 


——<——S —SSSE= dt defin.h = 
ttdefine DTZHELPP 27 /* define HELPP Text reference number 7 
tdefine DTKMENUS 28 /* define MENUS keyvord reference number */ 
tdefine DTZMENUS 29 /* define MENUS textreference number */ 
tdefine DTKRTREE 30 /»* define RTREE keyword reference number */ 
tdefine DTZRTREE 31 /* define RTREE text reference number */ 
tdefine DTKTABLE 32 /* define TABLE keyvord reference number */ 
tdefine DTZTABLE 33 /™* define TABLE text reference number */ 
tdefine DTKHOOKS 34 7» define HOOKS keyvord reference number */ 
tdefine DTZHOOKS 35 7 define HOOKS text reference number */ 
#tdefine DTKMAPIT 36 /7* define MAPIT keyword reference number */ 
tdefine DTKTEMPP 37 /* define TEMPP keyvord reference number */ 
mes sacl 38 /* this is our new communications ability */ 


tdefine DTKLAST 3947™ Last Ability number / 
dd Neu reference. | 
Increment DTKLAST. 


e 4) "dt_typdf.h" - Next we need to define the structure to store the ~ 
definition elements for our ability. We actually create a typdef of 
“structure type". This allows us to allocate a block of memory of this 
“structure type". (remember an ADAM in section 4). In our case let’s 
assume our Communication function needs the following data to 
perform its task. This information will be provided by the developer 
from the "script". 


a) Communication port id to use for communications. 

b) Modem Dial Command. 

c) Phone number to dial. 

d) login. 

e) password. 

f) file name containing list of data files to transmit/or receive. 
g) Modem Hang Up Command. 


————--__-_—_—_————————————— eee 
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step 2. Our structure type is DTTCOMUN. The following shows our 
structure: 


dt_typdf.h == SS 
DP XY OOODOOOOOOOO OOOO OOOO ASO OOVOOPOPOOOOEL 

7* COMUN definitions */ 

nifdef DTKCOMNUN 


typedef struct { 


COUNT num; 7% communication definition number 7 

COUNT port; /* Communication port id to use for comminications. 7 
TEXT xdial; 7* Moden Dial Command. */ 

TEXT *phone; 7* Phone number to dial. */ 

TEXT *login:; 7* login. “/ 

TEXT *passud; /* passuord. */ 

TEXT *filelist; /* file containing data files to transmit/’or receive. */ 
TEXT *hangup; 7% Modem Hang Up Command. */ 

+ DTTCOMUN: 

tendif 
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e 5) "dt_defin.h" - As you can see, we have defined text pointers in our 
structure. This implies that we will have text stored as strings in 
memory that is referenced by the pointers defined in our structure. In 
order for d-tree to support the memory required to store these strings 
we must go back and add another reference definition in "dt_defin.h". 
THIS IS ONLY NECESSARY FOR ABILITIES WHOSE STRUCTURE 
DEFINITIONS REFER TO STRING OF TEXT THRU CHARACTER 
POINTERS. Add another #define for this ability. This #define should 


one (1). DIKLAST must always be one greater than the last number 
assigned. Our example would look as follows: 


aa ss Sea tea ae RA dt_defin.h eens 
tdefine DTZHELPP 27 /7* define HELPP Text reference number */ 
tdefine DTKMENUS 28 /7* define MENUS keyvord reference number */ 
#define DTZMENUS 239 7 define MENUS textreference number */ 
tdefine DTKRTREE 36 /7™* define RTREE keyword reference number */ 
tdefine DTZRTREE 31 /7* define RTREE text reference number */ 
#define DTKTABLE 32 /* define TABLE keyword reference number */ 
tdefine DTZTABLE 33 7» define TABLE text reference number */ 
tdefine DTKHOOKS 34 /7* define HOOKS keyvord reference number */ 
tdefine DTZHOOKS 35 7» define HOOKS text reference number */ 
#define DTKMAPIT 36 /7* define MAPIT keyword reference number */ 
tdefine DTKTEMPP 37 /* define TEMPP keyword reference number */ 
wdefine DTKCOMUN 38 /7* this is our new communications ability */ 
udefine 39 7» this is for the text needed by our new ability */ 


wtdefine 


DTZCOMUN 
| DTKLAST 


4G 


Last Ability number */ 


dded New Reference for Text. 
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e 6) "dt_valid.h" - The next step is to assign a keyword for our ability 
which will be recognized at parse time. We must also tell d-tree the 
name of a "parsing routine" to call when it finds a section of a d-tree 
script which defined this ability. Parsing routines follow the naming 


steps below). First add the declaration of the parsing routine as shown 
in the following illustration. Then add an entry into the table 
DTTKEYWD dt_kwd{[]. Each table entry contains three fields: 


1) the keyword used in the script to identify this ability. 


es dt valid. h —=—=—=———= 
nifdef DTKHOOKS 7* if HOOKS 7 
COUNT DTPHOOKS(): /* HOOKS Parsing Function */ 


tendif 


«7 


tifdef DTKCOMUN 7* if COMMUNICATIONS 
COUNT DTPCOMUNC ); “* COMUN Parsing Function */ <«——/Add your parsing 
tendif declaration here 


Alibi LCCC LULUCLCELCLEELL ELLE LT Ltt ta 
7* Valid d-tree Script Keyvords */ 
ifndef IC 


Add your table entry here. 
Keyvord, parsing function, ref. 


DTTKEYUD dt_kud(J] = ¢ 
“* KEYWORD, PARSING FUNCTION, REF NO 


nifdef DTKCOMUN 
{ “COMMUNICATIONS’’, DTPCOMUN 
tendif 


DTKCOMUN } , /“™* FIELD  keyuvord */ 


tifdef DTKFIELD 
{ “FIELD”, DTPFIELD : DTKFIELD } , /* FIELD keyvord 7 
tendif 


always defined as sizeof(TEXT) for all abilities. Note the definition of 
this array: 


UCOUNT DTGSIZOF[DTKLAST] = { /* size of each element*/ 


9-4 d-tree Reference Guide 


9.1 Adding a New Ability 


or #define DTZ?????). We must ensure that our entry into this table 
is placed in the proper occurance of the array. In other words if our 
ability is defined as #define DITIKCOLUM 38, our entry for this ability 
must be in the 38 (remember the array starts with the zero (0) oc- 
curance of the array). This is why ability reference numbers defined in 
"dt_defin.h" must start with zero (0) and be numbered consecutively. 
The addition for our new ability is show below: 


dt_globl.h 
UCOUNT DTGSIZOFCDTKLASTI = { 7* size of each element */ 
sizeof(DATOBJ), “7% DTKDDODA »*/ 
sizeofCIFIL), 7* DTKIFILS 7 
sizeof¢( IIDX%), 7* DTKIIDXS */Z 
sizeofCISEG), 7* DTKISEGS' »*/ 
sizeof(DTTKEYBD), 7* DTKKEYBD */ 
sizeof( DTTFUNCT), 7* DTKFUNCT »*/7 
sizeof¢( DTTGROUP), 7% DTKGROUP »*/ 
sizeof¢ DTTRELAT), 7* DTKRELAT »*/ 
sizeof(DTTGENRL), 7* DTKGENRL Z 
sizeof( TEXT), 7* DTZGENRL ®Z 
sizeof( DTTIMAGE), 7* DTKIMAGE 7 
sizeof(DTTFIELD), /* DTKFIELD »*/ 
sizeof¢( TEXT), 7% DTZFIELD */ 
sizeof¢DTTCONST), 7% DTKCONST 7 
sizeof( TEXT), 7* DTZCONST 7 
sizeof( DTTPRMPT), 7% DTKPRMPT 7 
sizeof( TEXT), 7* DTZPRMPT »*/ 
sizeof( DTTSCANN), 7* DTKSCANN) 7 
sizeof€(DTTSUBFL), 7* DTKSUBFL 7 
sizeof( TEXT), 7* DTZSUBFL 7 
sizeof(DTTEDITS), 7% DTKEDITS */ 
sizeof TEXT), 7* DTZEDITS' 7/7 
sizeof¢DTTDFALT), 7* DTKDFALT 7 
sizeof TEXT), 7* DTZDFALT »*/ 
sizeof¢DTTCALCS), 7* DTKCALCS »*/ 
sizeof( TEXT), 7* DTZCALCS 7 
sizeof( DTTHELPP), 7* DTKHELPP 7 
sizeof( TEXT), 7% DTZHELPP »*/ 
sizeof¢ DTTMENUS), 7% DTKMENUS) »®/ 
sizeof( TEXT), 7* DTZMENUS */ 
sizeof(DTTRTREE), 7% DTKRTREE »*/ 
sizeof¢ TEXT), 7* DTZRTREE 7 
sizeof(DTTTABLE), 7* DTKTABLE */ 
sizeof( TEXT), 7* DTZTABLE »*/Z 
sizeof¢( DTTHOOKS), 7* DTKHOOKS */4 
sizeof( TEXT), 7% DTZHOOKS 74 
8, 7% DTKMAPIT */Z 


6, 7% DTKTEMPP 7 
sizeof(DTTCOMUN), 7* DTKCOMUN 7 br a Add your entry here. 
sizeof( TEXT), 7% DTZCOMUN 7 
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e 8) "dt_compi.c" - as illustrated in section four, the dt_compl function 
in d-tree will "dump" the parsed in ability definitions to disk, so that 
these definitions can be included in at compile time, thus eliminating 
the need for a parse. We must add our new ability to this function so it 
will handle it as well. 


a) First add the reference word define in step 2 to the table at the top 
of the file named 


TEXT *DTSNAMES[DTKLAST] = { 
This table follows the same occurance rules as defined for the table in 


The following shows our new entry: 
dt_compl.h 


TEXT *DTSNAMESCDTKLAST] = 
“DDODA", /* DTKDDODA »x/ 
“IFILS’, 7 DTKIFILS »*/ 
“FIDSS”, 7 DIKIIDXS “7 
“ISEGS’, /* DTKISEGS »*/ 
“KEYBD’, /* DTKKEYBD »*/ 
FUNCT’, 7% DTKFUNCT »*/ 
“GROUP, /* DTKGROUP »x/ 
*RELAT’, 7 DTKRELAT */ 
“GENRL", 7 DTKGENRL 7 
ean “* DTZGENRL 7 
“IMAGE”, 7* DTKIMAGE */ 
“FIELD, /* DTKFIELD »*/ 
ar 7* DTZFIELD */ 
“CONST”, 7% DTKCONST »*/ 
aie 7* DTZCONST 7 
“PRMPT’, 7 DTKPRMPT »/ 
yak 7% DTZPRMPT »/ 
“SCANN’, 7 DTKSCANN 7 
“SUBFL", 7 DTKSUBFL »*/ 
oe 7* DTZSUBFL »*/ 


“EDITS”, /7* DTKEDITS 7 
ae “* DTZEDITS 7 
“DFALT’, 7“ DTKDFALT 7 
rag 7* DTZDFALT »*/ 
“CALCS”, 7 DTKCALCS »-/ 
a 7™* DTZCALCS »*/ 
HELPP’, /* DTKHELPP »/ 
rat: “* DTZHELPP 7 
“MENUS”, 7% DTKMENUS »*/ 
ae 7™* DTZMENUS */ 
“RTREE”’, 7 DTKRTREE 7 
ie /* DTZRTREE 7 
“TABLE”, /* DTKTABLE »/ 
cae 7* DTZTABLE »*/ 
“HOOKS”, 7* DTKHOOKS »*/ 
saaeg 7™* DTZHOOKS 7 
“MAPIT’, 7 DTKMAPIT 7 
ies 7™* DTKTEMPP 7 


COMUN" » “** DTKCOMUN 7 
aser” 7* DTZCOMUN »*/ a Add neu entry here. 
I; 
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b) next we need to define a local work pointer in the function 
DT COMPL of our new ability type. Our new ability pointer definition is 
shown below: 


So SS =—=dt compl... 

COUNT DT_COMPL( filename) 

TEXT filenamel]; 7* file name to write definitions */ 
{ 

COUNT DT_CKHRD();: “* check to see if ability is already hard coded */ 
COUNT DT_COMPI(); 

VOID vtclose(); 

FILE *fopen(), fp; 

TEXT wrkfldC€DT_FLDLN]; 

TEXT wrkf1d2C€DT_FLDLN]: 

TEXT *urkptr;: 

COUNT linktyp=1: /7* type of source file to create */ 

COUNT useit;: 


FAST COUNT c,cc; 
DTTFUNCT *funcptr: 


DTTGENRL *gptr:; 
DTTRELAT *rptr; 


nifdef DTKCOMUN Add your work pointer here. 
DTTCOMUN *comunptr:; oe Ga 


tendif 


c) Use another ability as a guide (copy another and change it) to write 
a loop that will write your structure to disk. Use the same loop as any 


reference word. Here is our new ability: 


dt_compl.c 
Vart-t-t-t-1-1-1-1-t-1-1-1-1-1-¢-?-1-t-3-7-t-1-t-t-t-t-t-t ttt tt ttt ttt tt ttt tt tt ttt tt ttt ttt tt ttt ttt ttt tatet ta 
wifdef DTKCOMUN 

if (DTGNUMBREDTGCURGPICDTKCOMUN) && !DT_CKHRDCDTKCOMUN) > 

{ 


fprintf£( fp, *"DTTCOMUN DTSCOMUNDC] = { 7% COMUN */\n"); 


pptr=((DTTCOMNUN *)DTGPOINTC DTGCURGPICDTKCOMUN]):; 
for €c=@; c<DTGNUMBRCDTGCURGPICDTKCOMUN]: ++c) 

{ 

fprintf£(fFp,"°C€ “3; 7** beginning of record */ 


Porint(tfs. 744.74." ; 
comunptr—>num; 7% communication definition number */ 
comunptr-—?port); 7% Communication port id to use for comminications. 


if (comunptr- >dial) 

forinti( fe, “\"As\” 6U pptir dial >: 7% Moden Dial Command. “/ 
else 

fer intiitia SN 3% 


if (comunptr->phone) 
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fprintf£ fp, "\"Z%s\" “, pptr->phone):;: 7* Phone number to dial. */ 
else 
fprint£e fp, a a 


if Ccomunptr—>login) 
fprint£fp, “N\°As\”" “, pptr-> login): 7* login. aS 
else 


FerintPtin, “WN 33 


if (comunptr—>passud) 

fprintf£( fp, “\"As\N" “, pptr—>passud): 7* passuord. 7 
else 

forintitiae, wo \ 73: 


if (Ccomunptr—>filelist) 

fprint£e fp, "VAs" “, pptr-—>Ffilelist): “* file containing data files * 
else 

Foriatit te, ."s. >; 


if (comunptr—->hangup) 
fprintfC fp, “N\"4%s\" “, pptr—->hangup): 7* Modem Hang Up Command. “/ 
else 


Sprinthcrpe “NA Oss 


fprintfC fp,” * .\n"): 74 end of record */ 


++comunptr; 


Bg 
fprint£ fp, "F:\n\n"): 7* end structure */ 
+ 7% end COMUN */ 
tendif 


atatatatatetsistatsiaisisiaisintaisininininioistsisisteii ttt ttt ELE Lee LE Let ttt ttt t th tet tei tt tert tet htt ei tet A 


e 9) The next step is the most difficult part of adding an ability. It is up to 
ine user to define the syntax within the script for the new ability, and to 
write a parsing routine that will initialize the ability structures with the 
definition from the script. When the primary parsing routine detects the 
ability keyword, it will build a work buffer with just that ability’s section 
of the script. The address and the length of this work buffer is then 
passed to the parsing routine that was defined in the table defined in 
step 6. This parsing routine must be defined as receiving the following 


parameters: 

COUNT DTP?????(kwptr,parsebuf,len)/* ????? Parsing Routine*/ 
DTTKEYWD *kwptr; /* ptrs to keyword structure */ 
FAST TEXT *parsebuf; /* address of buffer with definition */ 
COUNT len; /* length of buffer */ 


9-8 d-tree Reference Guide 


9.1 Adding a New Abilit 


e There are plenty of examples of parsing routines within d-tree, as every 


below are listed some of the routines d-tree provides to aid in writing a 
parsing routine: 


cn 
DT KEYNM - Validate token as a valid key name. 
DT TOKNX - get next token from the temporary buffer passed to 
the parsing routine. 
DT GENRL - Validate Token in a General Table. 
DT TDODA - validate token as valid doda fiel symbol name. 
DT CPMEM -reallocate ability memory. 
There is a skeleton parsing routine in the file “dtpstart.c' that may be 
used as a "starter" for your own parsing routine. This file is shown 
below with conceptual comments on the general necessities of a parse: 
dtpstart.c 
tinclude “dt_defin,h’ <«——————————————-. Aluays define d-tree’s header. 
7, YEE PE DE DE DEDEDE DE DE HE HE D4 DE OE DEE DE DE HE DE DE D4 DE EE DEE DE dD DE De Dd DE 
7* Valid symbols */ 
DTTGENRL dt_genedtl] = ¢ 
ma C’*MANDATORY™ »DTETMAND +, 7+ mandatory entry */ 
C°MAND_FILL” .DTETFILL +, 7™* mandatory fill */ 
, Saar |e 7* terminaton Indicator */ 
+; 
Ve ttt tot. tote tata ta tatatetatatataiatataiataiaiotaioistataiaiaiataiaiataiat’l 
If there are certain tokens defined in your syntax for special 
meanings they may be defined in a DTTGENRL type table at the top of 
your parseing routine. The function DT_GENRL can be used to deternin 
if a token in in this table. Example of EDITS table. 
Pee tt tt tot t tot ttt t tata at tat atat tots tatataiatateiatoiaia£aiaistatataioaiciotctciaicictciet.t.i.t.i.i.i.t.i.t-.t.i.t.1.1.1.3.1.1-1.1.3.1.1.1-74 
hei DTP?7777 K/ 
COUNT DTP?77777( kuptr, parsebuf, len) 7* T?77T? Parsing Routine a / 
DTTKEYUWD *kuptr:; 7* ptrs to keyword structure M/ 
FAST TEXT *parsebuf; “7* address of buffer with definition / 
COUNT len: 7* length of buffer */ 
{ 
COUNT atoi(); 
TEXT *strbuf, *endbuf; 7* start end end buffer pointers a7 
COUNT notused: 7* uvork flags «7 
DATOBJ *DT_TDODAC ); 7* validate token as valid doda symbol “/ 
COUNT DT_CPMEMC ); 7* reallocate ability memory */ 
COUNT DT_KEYNMC ); 7* validate token as valid key symbol */ 
COUNT DT_TOKNX¢ ); 7* get next token from parsing buffer */ 
i COUNT DT_SPTRS(); 7* reset relate pointers "7 
DTTGENRL *®DT_GENRL(), *gptr; 7* general table validate / 
DTT?7777 *777?ptr:; 7* work pointer to 77777 structure 7 
DTTRELAT *rptr,**rptrZ:; 7* uork pointer to relate structure */ 
DATOBJ *dodaptr:;: 7* work pointer to the doda */ 
TEXT xT TTLxt; /* pointer to 77777 text */ 
TEXT token(DT_TOKLN]; 7* token work buffer “/ 
COUNT G,cce: 7* work Fields / 
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COUNT section: 7* parsing stage indicator */ 

COUNT TT7T7T7?no; 7™* T7777? number work field 7 

COUNT noof?7777 = @; “7* number of 77777 *7 

COUNT noofflds = @: “7* number of fields involved */ 
COUNT textlen = @: “7* total length of all text */ 
COUNT reset = @: 7* need to reset RELAT pointers »*/ 
COUNT length: 7* token length */ 


Here ve have defined many common work variables that can may 


be needed in a typical parsing routine. 


uerr_cod=@; 
strbuf=parsebuf: 
endbuf=strbuf+len-1; 


/* first count the number of 777 by counting 777 */ 
while €¢€length=DT_TOKNX( token, &strbuf , &endbuf, 
&notused, &notused, &notused, &notused, &notused) >) 


{ 
if (DT_KEYNM(token)) continue: “* bypass key names */ te 
if (DT_TDODACCCDATOBJ *)DTGPOINTC DTGCURGPICDTKDDODAI), token)? 
{ ++noofflds: continue: } “* count fields */ 
if (€gptr=DT_GENRL( dt_yours, token,@))) € ++noof7?7777; continue: } 
textlen+=Clength+1); /* add up text length-add one for space or nul]*/ 
} +. 


7™* reset buffer pointers */ 
strbuf=parsebuf:; 
endbuf=strbuf+len-1; 


The first thing that must be done is to count how much allocated 
space is necessary for this ability. Ue need to determin both hou many 
structures need to be allocated as well as how much text space is needed. 


Aaisisisisinisisisiniginisisiainiaisisisiataisisiaiaiaiaiaiainiaisiaiaiaisisisiaieistcicde LLL LLU ciiliiiiiitt ta 
“7* Allocate 77777 Space »/ 
if CnoofT?T?TT7) 
{ 
if (DTGNUMBRE DTGCURGPIJCDTK77777]) reset=1: 
if (DT_CPMEM( &DTGNUMBRE DIGCURGPI£ DTK77777), noof77777, 
CTEXT **) &DTGPOINTC DTGCURGPICDTK77777), sizeof( DTT?77777) )) 
return( ERR_66@1); 
DTGSIZOFCDTK7777 7 IJ=sizeof( DTT77777): 


7* Allocate 77777 Text Space */ 
777txt=DTGPOINTLE DTGCURGPJCDTZ77777]: “7% save old global ptr */ 
if © DT_CPMEM(C &DTGNUMBRE DTGCURGPIJLDTZ777771], textlen, 
CTEXT ™*)&DTGPOINTE DTGCURGPICDTZ77777), sizeof( TEXT) )) 
return( ERR_6682Z);: 
DTGSIZOFC DTZ77777 1]=sizeof( TEXT); 


Here we allocated the space, first for the structures, and then for 
the text. 


St ee eri ae ap pi ate 
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/* neu ptr = new global plus (old address minus saved global) */ 


for €c=@; c<CDTGNUMBRC DTGCURGPICDTK77777I]—-noof?7777); ++) 
3 
if (?777?ptr— edttxt) 
{ ecc=77TTptr—- -edttxt—TT77txt: 


if (77?ptr—-— addtxt) 
€ cce=777ptr—addtxt—T77txt: 


+7 iptrs 
> 


777txt+=( DTIGNUMBRE DTGCURGPJCDTZ77777IJ-textlen): 
+ 78. Onda 1f TIT er 


We need to loop thru and reset any text pointers for any previously 


parsed ability of this same type. 


TT7TTno=kuptr—*ocurl(Ol; 7% set TITTT no */ 

if (kuptr-?ocur(1]) All parsing routines need 
{ to contain this logic 
kuptr—>ocur(@)]=kuptr—>ocurl1I: -| for ability reference 
kuptr—>ocurliJ=@: numbers. 

} 

else 


kuptr—>ocur([@1]=G@: 


section=@: /* uork field */ 
uhile ¢¢€length=DT_TOKNX( token, &strbuf, &endbuf, 
&notused, &notused, &notused, &notused, &notused) )) 
{ 
suitch (section) 
1 
case @: /7™* example suitch */ 
if (!€gptr=DT_GENRL(dt_yours, token,@))) 
{ uerr_cod=ERR_1@@A: goto reterr; } 
TT Tptr— >field=your structure ficld: ———————— oor 
+} “7* end suitch */ 
+} 4 end looping thru tokens */Z 


return(@):; 


reterr: | 

printf ’token=’ %s’\n"', token); 
return(€uerr_cod); 

} 7* end of parseing routine */ 


Nou write a loop that re-parses the same buffer. This time 


initilizing the allocated buffers. 


‘ 2 ae errnannnnnnnmnaannenannannnnnenmennnsennenneneenemenneeeenemnanenenenn=eeenesnennneeeeneeeneeee ae 2 
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e 10) The last step is to write a function, that given a pointer to the 
structure will perform the appropriate task. Following d-tree’s naming 
conventions, our new ability function whould be named DT COMUN, 
although it doesn’t make any difference. Our function would receive a 
pointer of our ability type: 


COUNT DT _COMUN(ptr) DTTCOMUN “ptr; 
Adding a new ability is a very powerful feature in d-tree. Steps 9 and 10 


are the most difficult. The EDITS parsing function is a good function to 
study. It does not have a terribly complex syntax. 


Se a a et a ee ee oe Me 
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9.2 Adding a New FIELD Input Attribute. 
In order to a a new input attribute for the FIELDS ability do the following steps: 


e 1) "dt_typdf.h" - Add a new #define reference for the new attribute in 
dt_typdf. Input attributes definitions begin with DTIA????. 


dt_typdf.h 


“7* input attributes */ 


tdefine DTIANONE @x6B /7* no attribute */7 
tdefine DTIANOCHG @xGi /7** no changes allowed via input */ 
tdefine DTIANUM 6x82 /** numbers only can be entered */ 
tdefine DTIACAPS 6x84 7* convert every char to caps */ 
tdefine DTIANMCAP 8x88 /7* name input attribute */ 

tdefine DTIAFUCAP @xX16 /7* first letter of first word of field to be caps */ 
tdefine DTIAAUCAP @x260 7 first letter of all vords in field to be caps */ 
tdefine DTIAPROCT @x4@ /7* protected field-cursor vill not enter */ 
tdefine DTIALOKUP Bx8G@ /7* lookup detected */ 

tdefine DTIASCROL @X1@8 /* scroll alloved */ 

tdefine DTIATABLE @X2@@ /* TABLE_IN convertion */ 

tdefine DTIAHELPP @xX40@ /7* display HELP TEXT automatically */ 
tdefine DTIAGOTO @x8GG 7 display GO TO another field */ 

tdefine DTIASP1 @X186806 /“* special needs 1 »*/ 

tdefine DTIASPZ Bx2G08 /7* special needs Z *Z 

udefine DTIASP3 @x3G8G /“* special needs 3 */ 


ttdefine DTIASP4 Bx8GG0 /7* spe 
Add a neu ttdefine here. 


@ 2) "dtpfield.c" - Add new attribute keyword for d-tree script in the input 
attribute table at the top of "dtpfield.c" 


SE = eee = dtpfield.c 
We ttt tt tt tt tt a tt tt et t-t-2-0-t-t-2-t-2-0-2-4-4-2-1-2-1-1-1-94 

7* VUalid INPUT Arributes */ 

DTTGENRL dt_iatr(] = ¢€ 


C’NONE™ » DTIANONE }, 
C**"NOCHANGE”’ » DTIANOCHG }, 
C°"NUMERIC™ » DTIANUM J. 
C““ALLCAPS” s BDTIACAPS. +, 
C""NAMECAPS” » DTIANMCAP }, 
C{"FRSUORDCAPS” , DTIAFUCAP }, 
{"ALLUORDCAPS” , DTIAAUCAP }, 
C""PROTECT’ » DTIAPROCT }, 
<*SCROLL” » DTIASCROL }, 
CC" TABLE_IN" » DTIATABLE }, 
C°AUTO_HELP” . DTIAHELPP }, 
{""GOTO" . DTIAGOTO }, 
{""NONE_NONE” . DTIASPI bo 
{’NAME_NUM"” , DTIASP3 }, 
{""NONE_NUM” , DTIASP4 as 
{°"" ,-1} 7* terminaton Indicator */ 
3 


e 3) Logic must be added to the appropriate function to address this 
new attribute. Most input attributes are handled in d-tree by the low 
level input routine "dt input" in file "dt_input.c". Some are addressed 
before the input routine is even called, in the "field out" routine 
(DT _FLDOT in file "dt_field.c’). 
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9.3 Adding a New FIELD Output Attribute. 


Output attributes fall into two categories: attributes that require no special 
screen control, and attributes that do require special screen control. In order to 
a new output attribute for the FIELDS ability do the following steps: 


e 1) "dt_typdf.h" - Add a new #define reference for the new attribute in 
file “dt_typdf.h". Output attributes are defined at the bottom of this file. 
lf special screen control (escape sequences) are necessary to make 
sure the #define DT _MXSEQ is set to handle enough sequences. 


#detine DT MXSEQ 6 /* Maximum characters in pevpoal edie aieiisibe aa 


poe ens Sa = dt_typdf.h aaa i 
[7 OUTPUT ATTRIBUTES */ 
7* note-do not assign (-1) to any screen seq or keyboard key “7 
7 for (-1) is used to detect termination */ 
i7* remember that all screen sequence numbers must be numbered a7 
|“* sequentually without skipping any numbers between the first */ 
1“ and last number “/ 
“7* there are tuo types of output attributes for a field “/ 
“7% screen control seq are one type, and simple output attributes that */ 
7* do not involve special screen seq are another a7 
“* regular output attributes -no screen special seq a7 
udefine DTOAGIDLIN °_° /* input guide line character “7 
udefine DTOANOLIN (-2) 7* do not display input guide lines a 
udefine DTOATABLE (-3) /* TABLE_OUT convertion nS 
tdefine DTOAZEROS (-4) /* Allow Zero to display (non-zero suppress) a 
Ve tat otatatatatatatatatatatatatatatet.t.t.t.04 

7* screen special sequence output attributes u/ 
udefine DTSCFRS (-10) 7/4» define first screen sequence number */ 

tdefine DTSCLST (-39) /7™* define last screen sequence number */ 


e 2) "dtpfield.c" - add the new attribute to the valid output attribute table 
in the field parsing function as shown below. The "dtpfield.c" module 
must then be recompiled. 


dtpfield.c 


Vet atatototatatatatatatatatatctatcLL rer th ttt eA 
7* VUalid OUTPUT Arributes */ 
DTTGENRL dt_oatrf{} = { 


, age SY tae sDTSERT 3; 
C° INPUTRI” ~RDISELOTUS. >, «+—-} Add your new attribute to this table. 
a | a (pr acu. +, 


< 

HL pUTSLHL. 3. 

{" EOL” »DTSCEOL }. 

C*"*NOLINES” , DTOANOLIN } 

C°TABLE_OUT’ ,DTOATABLE } 

C""ZERO” . DTOAZEROS } 

{**BLACK”™ »DTSCBLACK }, 7* black */ 
C*BLUE” .DTSCBLUE }, 7™* blue / 
GREEN” » DTSCGREEN }, /“* green */ 
C“CYAN” ,DTSCCYAN 3, 7* cyan “/ 
{RED . DTSCRED +, “* red a7 
C**MAG” ,» DTSCMAG +, 7* magenta / 
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@ 3) "dt_keybd.h" - If the output attribute definition is to come from the 
TERMCAP file (screen control sequence) add the attribute to the table 
shown below: 


eens ene == dt keubd esses 
“7% Ualid KEYBD types symbols */ 

{ESC DIKBESE?. 

{C"CR" . DTKBCR. “* Cr-Return on keyboard a7 
C"BU" , DTKEBUY, “7% back-up on keyboard “7 
<"DG” , DIKEBDC}. “* delete character a7 
ct. | PIRES 7* insert char a7 
{Du , DTKBDU}, 7% doun key "7 
{"UP" ,DTKBUP}, 7* up key “/ 
C"PD” ,DIKBPD?. 7* page-—douwn 7 
CPU . DTKBPU., /* page-up a / 
CLF 4 VERGe?. 7% left key 7 
RT =. DIKERTS. “* right key al 
CHM” , DTKBHM}, 7* home key / 
CEN” ,DTKBEN?}., 7* end key aS 
iL, DIKEILS; “7* Insert Line 7 
{DL , DIKEDL?. “7* Delete Line / 
CAD ,DTKBAD}, “7* Auto dup-Defaults aS 
FS , OTRSrSse, 7“ Print Screen 7 
(“Fi 6  DIKBFIAS, “* function key Fl al 
Fa" 4 DIKE Ze. 7* function key F2 m/ 
CFS" . DIKES}. “* function key F3 m7 


The parsing routine which reads the TERMCAP file must then be recom- 
piled. Compile the module "dtpkeybd.c". 


e@ 3) "dtermcap.h" - If you would like this output attribute to be prompted 
in the dtermcap program enter the attribute in the following table and 
recompile the dtermcap program: 


dtermcap.h 


PEPE 4 DK DE DE DE DEDEDE DE DE DE DE HE DE Dk Dk Dk Dk ne DE DE DE DE Dk Dk DE DE DE De DE Pd DP ED 


“7* Valid KEYBD types symbols */Z +——-/} look at this table in dtermecap.h 
DTTGENRL dt_gencap(] = 


PERCE COP) TAM. os kwaln Sob ere Oe ee ee ay 
eR COE. CORP NOG. 6s ooo ek kw ee ae Noles a ee ee **, DTKBESC}., 
Cregeen ae ae a he eke no lek ee oe ie oe  DEREL RO: 
PREMISE EE ONE cs con © atin tara we ae ow ah a rela Boer ame ee ae | DTKBBU}, 
DOLE CEAPEG CEE cae owas eee oe ee ee ** DTKBDC}, 
"ERSECE. CHSPRCCEE So oss KA wc Rw eee eee KS “DIKE IGC.. 
Pn ea ar ae ee ee ee Pee ee a ee ee ee ey ee een “ DTKBDUW}, 
POE eR ar Le te re oe ee eg ee ee ER ee pe Ee LE Eh ee * DTKBUP}, 
5 ARG eb es Wo als ae Oe ew ee Gy DIKEE OY: 


Sr 


Cr  e ) 


Cr ee | 


"TNGORT Lind KheG. 4. cs 65545 bes Ch aca ees eee is 
Delete: Link ROU c4. 6 ic oes reese hs shea eeeee ees - 
gee de: COP) VU oa pe oa ea te eee eewen arena : 
"Print Screen Key Coptional-skip in DOS)........ : 
VERT RR ioe eo ee “ns So acl tan ale ee Wes mace ee ee ** DTKBHELP}, 


< 
{ 
{ 
{ 
3 
C 
c" 
c" 
< 
c" 
c" 
{ 
" 
i 
C 
{ 
< 
{ 


d-tree Reference Guide 9-15 


9.3 Adding a New FIELD Output Attribute. 


e 4) Screen control attributes will be handled by the DT _SCSEQ function 
in "dt_misci.c" and should require no more modifications. Other special 
purpose attributes may require changes to the code where output is 
done. See "dt_const.c" for constant out function and "dt_field.c" for 
field out function (ODT FLDOT and DT FLDLO). Refer to the function 
reference section for function descriptions. 


_—_——— eee 
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9.4 Adding a New EDIT. 


In order to add a new field edit to d-tree do the following steps: 


e 1) "dt _typdf.h" 


"dt_typdf.h" after the last edit defined. See below: 


/* edit 


types 7 


dt_tupdf.h 


- Add a new #define identifier for the edit in 


/x* remember edit type numbers must start at one and be in seq order */ 


“7* You MUST define DTETLAST to be same as last edit number al 
tdefine DTETMAND 1 /7“* MANDATORY edit. / 
ttdefine DTETFILL 2 /7* MANDATORY fill edit. a / 
tdefine DTETDATi1 3 /7** DATE edit.-MMDDYY aS 
tdefine DTETDATZ 4 7 DATE edit.—MMYY / 
ttdefine DTETDAT3S S /7* DATE edit.—MMDD aS 
tdefine DTETTABL 6&6 /** TABLE edit. / 
tdefine DTETDUPK 7 /7* Duplicate key edit. / 
tdefine DTETUALD 8 /7** VALIDATE edit. aS 
tdefine DTETSFLH 9 /7* Subfile Hash edit. af 
tdefine DTETSFLS 1@ “™* Subfile SAME as edit. 7 
tdefine DTETSFLN 11 “* Subfile NOT SAME as edit. */ 
tdefine DTETUSRE 12 “™ User defined edit / 
Add your edit ID here. 
tdefine DTETLAST 13 “* Last Edit Type Number “/ 


Increment this number. 


32) dt edits.c" 


Write your own edit routine, and add the call to your 


edit routine to the switch in the DT EDITS routine found in "dt_edits.c' 


e 3) "dtpedits.c" - 
_to the valid edit table in the file "dtpedits.c". 


Add your new edit reference with your function name 


= dtpedits.c aia 
DTTGENRL dt_genedt( DTETLAST+1] = 
ha ,@ : ,DT_ RETR}. 
C*"MANDATORY™ ' DTETMAND . DT_EMAND, 7* mandatory entry “/*", DT_EMAND}, 
C'°MAND_FILL” ~OTETFILL . “DT_EFILL, 7 mandatory £111 us, DT _EFILL?, 
{"DATE_MMDDYY” ,DTETDAT1 , "“DT_EDATE. “™ date edit-MMDDYY »/*’, DT_EDATE?, 
C’DATE_MMYY” .DTETDATZ , “DT_EDATE, “* date edit—MMYY “/", DT_EDATE?}, 
{**DATE_MMDD”™ »DTETDATS , ““DT_EDATE, “* date edit-—MMDD “/*", DT_EDATE}, 
C"TABLE™ ,DTETTABL , ““DT_ETABL, 7™ table validate “se  DT_ETABL?. 
{"DUPKEY™ »DTETDUPK , ‘“DT_EDUPK, “™* duplicate keys “/". DT _EDUPK?, 
C""UALIDATE” »DTETVALD , “DT_EVALD, 7™ validate edit W7””.. DY EUALID , 
{"*SFLHASH” sDTETSFLH , “DT_EDSFL, ~™ subfile hash uf”, DT _EDSFL}. 
C*°SFLSAME” sDILISFLS . DT_EDSFL.. “™ eubfile sane Me ESE els 
C"SFLNOTSAME” ,DTETSFLN , “DT_EDSFL, 7™* subfile not same »/*’, DT_EDSFL}, 
{“USER_EDIT” »DTETUSRE , “DT_RETRN, “* user defined edit »*/"’, DT_RETRN}, 
ce Pies! | , DT_RETRN} 
a 


Viet atatattatatatatatatatatatatatatatatatataiaiatatatatatatatatatataioiaiaisaA 


Add your new edit reference here. 


e 4) Recompile idisedite c' and "dt _edits.c". 
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* REFERENCE NUMBERS- 


APPENDIX A 


Function Reference 


Function Function 

Name Number Description = © 

DT ADREC 30 Add Record to ctree file. 

DT ALDOD 1C Doda Alignment. Given a DODA pointer, deter- 
main offsets and addresses. 

DT ALIGN 68 Set or verify addresses in DODA and determain 
machine alignments. 

DT AVREC 114 Add a Variable Length Record. 

DT BHELP rye Build help text index file. 

DT CALCS 83 CALCS processing function. 

DT CALMP 109 Perform field mapping with a calculation. 

DT CKHRD 115 Check to see if an ability is hard coded. 

DT CLEAR 23 Clear the Screen. 

It CLE. 50 Clear to the end of a line. 

DT CLRBK SF Clear a portion of the screen. 

DT CLRLN 116 ri the screen from line number x to line num- 

er y. 

DT CMDOD 110 Sere two dodas and set mapping flag for 
file conversion. Used by DT_REFMT function. 
(ie: change fields, record length) 

DT COMPI iF Convert Allocated Typdef structures to compile 
time initilizion C code-Incremental file struct. 

DT COMPL 54 Convert Allocated Typdef structures to compile 
time initilizion C code. 

DT CONST 20 Display Constant (Contant out). 

DT CPMEM 2C Ability Memory Allocation Routine. 

DT CVDOD 117 Convert data as define in one doda into the for- 
mat defined by another doda. 

OT DELEr 37 Delete characters from a string. 

DT DFALT 78 Default logic-field level. 

DT DFIMG 92 Default logic-IMAGE level. 

DT DFINI 6D Execute Default Definitions 

DT DLREC 2D Delete a c-tree record. 

DT DODBK 7B Check to see of a doda field address if blank or 
zero 

DT DODTS 89 Create default d-tree script. 

DT DOINT 34 Initilize c-tree file record buffers. 

DT DOMSG 91 Display a message on the default message line. 

DT DOPAD 35 Pad fields in c-tree file record buffer. 
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DT DORTS 
DT _DTICP 
DT DTISP 
DT EDATE 
DT EDITS 
DT EDRRD 


DT_EDSFL 
DT EDUPK 
DT_EFILL 
DT_EMAND 
DT EQREC 
DT _ETABL 
DT _EVALD 
DT _EVALU 
DT FLATI 
DT FLATO 
DT FLDIN 
DT FLDLO 
DT _FLDNM 


DT _FLDOT 
DT FLDTX 
DT FRAME 
DT FREEE 
DT FSREC 
DT _FSSFL 
DT FUNCT 
DT_GENRL 
DT _GHELP 
DT_GPINN 
DT_GPOUT 
DT HELPP 
DT HOOKS 
DT IFILS 
DT IMAGE 


DT_IMGAL 
DT_IMGIN 


DT IMGLG 
DT _IMGMV 


DT IMGOT 


Create default r-tree script 

"In Comming priority" for DT_PSFIX function. 
"In stack priority" for DT_PSFIX function. 
EDIT routine-Dates. 

Primary field edit function. 

Read Read Record edit to prevent muliuser in- 
terferance. 

Edit a subfile. 

EDIT routine-Duplicate Keys. 

EDIT routine-Maditory Fill. 

EDIT routine-Mandatory Field. 

Equal Record function. 

EDIT routine-Table Edit. 

EDIT routine-Validate with another file. 
Evaluate a postfix expression. 

Import a Flat File to a c-tree file 

Output a data file to a Flat File. 

Input a field (Field In). 

Field out-low level 

Validate token as valid field symbolic name in 
DODA 

Display Field (Field Out). 

Convert a Ascii Field to Valif Field Type. 
Draw a Frame on the screen. 

Free All Ability’s Allocated Space 

Get the first record in a file. 

Read the first subfile record. 

Validate token as valid user defined function. 
Validate token to a GENRL type table. 

Get help text from a text file. 

Read a group from Disk. 

Write a group to Disk. 

HELPP routine. 

Hook function. 

Open IFILS. 

IMAGE OUT then IMAGE IN. Combination 
DT IMGOT then DT IMGIN. 

IMAGE ALL-Display and Input a range of 
IMAGE’s. 

Input an Image (Image In). Series of 

DT _FLDIN’s related to the provided IMAGE. 
Redisplay IMAGE’s from log. 

Same as DT_IMAGE but allows user to change 
IMAGE coordinates. 

Display IMAGE (Image out). Series of 
EGE & DT_CONST related to provided 
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DT_INAME 
DT_INBUF 
DT _INDOD 
DT_INPUT 
DT _KEYBD 


DT_KEYCK 
DT_KEYCV 


DT _KEYNM 


DT_LOCAT 
DT LOCPT 
DT_MAPIT 
DT MENUS 
DT_MNUCK 
DT MPDOD 
DT _MSKOT 
DT_NSERT 
DT NXREC 
DT_NXSFL 
DT OFSET 
DT _OVLAP 


DT PARSE 
DT_PBUFF 
DT_PRMPT 


DT_PSTFX 

DT PVREC 
DT RCDLN 
DT RDBUG 
DT_REFMT 
DT _RSORT 


DT RSORT & 


DT CMPAR 


DT_RTRE2 
DT RTREE 
DT _RWREC 
DT SCANN 
DT SCGET 


DT SCSEQ 


76 
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Return the associated IMAGE number for token. 

Initilize a memory buffer to nulls. 

Initilize all addresses defined in the DODA. 

Low Level Keyboard Input Routine. 

Keyboard Initilization routine. Load temporary 

parsing buffer with terminal definition 

fromTERMCAP file for the DTPKEYBD funtion to 
arse. 

Validate Token valid termcap token. 

Convert key number identifier to actual key 

number. 

Validate token as a key symbolic name for a 

index. 

Position Cursor on Screen. 

Locate cursor for printed output. 

MAPIT routine. Map one field to another. 

Menu Function 

Check menu condition definition for a match. 

Map data for the DT REFMT function. 

Strip Mask Characters off input field. 

Insert a character into a string. 

Get next record. 

Read the next subfile record. 

Calculate the offset of a DODA entry. 

Detect if one image or field overlays another on 

the screen. 

Primary Parsing Function. 

Load temporary parsing buffer. 

Prompt routine. Provides key no, target, sig- 

nificant length for accessing a c-tree file. 

Convert an expression in infix form to postfix. 

Get previous record. 

Calculate record length from DODA definition. 

RELAT debug function-display RELAT structure. 

Reformat a c-tree file. 

Sort the RELAT structure. 

Sort RELAT structure. 

Compare used by DT_RSORT to determain 

order. 

R-tree interface secondary substitution function. 

r-tree front end 

Rewrite a c-tree record. 

Scan routine for c-tree data file. 

Do x number of PREVKEY’s and then read in 

record. Used By DT_SCANN for record selec- 

tion. 

Output Screen Control Sequence. 
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DT _SETTY 


DT SFCAD 
DT SFCLD 
DT SFHAD 
DT SFHDL 
DT SFHLD 
DT SFLAD 
DT SFLDL 
DT SFLLD 
DT SFLNW 


DT SFLOT 
DT SFLRM 
DT SFLRW 
DT SPTRS 
DT STALN 
DT SUBFL 
DT TDODA 
DT TODAY 
DT TOKEN 
DT TOKKW 
DT TOKNX 
DT TSPLT 


DT UNHID 
DT UNPAD 
DT _UNPAK 


DT _UNPOP 


DT_VLINN 
DT VLOUT 
DT _XTRCT 


DTVIMAGE 


DTPCALCS 
DTPCONST 
DTPDFALT 
DTPEDIT2 
DTPEDITS 
DTPFIELD 
DTPGROUP 
DTPHELPP 
DTPHOOKS 
DTPIFILS 


ue 


Set TTY line to get one character at a 

time. (Unix) 

Subfile Add for parent and child 

Load child subfile. 

Add subfile to disk-high level. 

Delete subfile from disk-high level. 

Load Subfile Routine-high level. 

Add subfile to disk-low level. 

Delete subfile from disk-low level. 

Load Subfile Routine-low level. 

Add a new record to a subfile.(extend the sub- 
file-unlimited sfl only). 

Display subfile (SUBFL Out). 

Remove a subfile from disk (unlimited sfl) 
Rewrite a record back to a subfile. 

Set relationship pointers in RELAT structure. 
Initilize (set align) the alignment array. 
Maintain a Subfile. (Subfile input routine). 
Validate token is a symbolic name in DODA. 
Get System Date 

Get next token from file. 

Validate token as valid ABILITY keyword. 

Get next token from memory buffer. 

Token Split function. Convert a token in the 
form of XXXXXX(yyy) into yyy and XXXXXX. 
Display the hide screen buffer to the screen. 
Unpad a record structure. 

Low level Unpack. Unpack one buffer into 
another. 

Un-pop (clear and refresh behind) a image from 
the screen. 

Un-Pack Variable Length record. 

Pack Variable Length record. 

Extract a subset of relations from RELAT struc- 
ture. 

Get IMAGE pointer given IMAGE number. Often 
used to validate a IMAGE number. 

Parsing for CALCS keyword. 

Parse CONST keyword. 

DFALT (default) parsing routine 

Edits Parsing sub-function to handle text strings. 
Parsing function for EDITS. 

Parse FIELD keyword. 

Parse group definition. 

Parsing function for HELPP keyword. 

Parse CALCS Keyword. 

Parsing function for IFILS. 


SIDiniirsereemesre arenes eee 
Appendix A Page iv 


d-tree Reference Guide 


Appendix A - Function Listing 


DTPIMAGE 
DTPKEYBD 


DTPKEYST 
DTPMAPIT 
DTPMENUS 
DTPPRMPT 
DTPRTREE 
DTPSCANN 
DTPSUBFL 
DTPTABLE 
DTCATADI 
DTCATADO 
DTCATCSP 
DTCATDIF 
DTCATDOD 
DTCATINC 
DTCATPAR 


Last ref number used = 134 


Parse IMAGE keyword. 

Parse KEYBD function. Used to parse the 
termcap definition. 

Sort Keyboard array. 

Parse MAPIT keyword. 

Parsing Routine for MENUS 
Parse for PROMPT keyword. 
Parse r-tree interface definition 
Parse for SCAN keyword. 

Parse for SUBFILE keyword. 
Parse TABLE keyword. 

Ability Dictionary In/Delete routine 
Ability Dictionary Out routine 
Create C language source specs 
File difference routine 

Create doda stucture 

Create Incremental Structures 
Create Paramter file 


Note that error codes are hex in order to accomodate the first two digits to rep- 
resent the module and the second two digits to be the error number within the 
module. Using hex allows more than 99 modules and more than 99 errors per 
module. Remember functions that return a value greater than 7FO0O must be 


declared as UCOUNT. 
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ERROR MESSAGES 


ERROR CODE 


e ERR 1001 0x1001 
e ERR_ 1002 0x1002 
e ERR 1003 0x1003 
e ERR _ 1004 0x1004 
e ERR_ 1005 0x1005 
e ERR_ 1006 0x1006 
e ERR_ 1007 0x1007 
e ERR 1008 0x1008 
e ERR_ 1009 0x1009 


e ERR_100A 0x100A 
e ERR_100B 0x100B 


e ERR_100C 0x100C 
e ERR_100D 0x100D 


e ERR_1101 0x1101 
e ERR_1102 0x1102 
e ERR_1103 0x1103 
e ERR_ 1601 0x1601 
e ERR_1602 0x1602 
e ERR_1603 0x1603 
e ERR_1604 0x1604 


e ERR_1605 0x1605 
e ERR_1606 0x1606 


e ERR_1801 0x1801 
e ERR 1802 0x1802 


e ERR_ 1803 0x1803 


e ERR_1901 0x1901 
e ERR_1902 0x1902 
e ERR_1903 0x1903 


DESCRIPTION 


DTPFIELD-Symbolic Name Not Found In DODA 
DTPFIELD-Invalid Input Attribute 
DTPFIELD-Invalid Output Attribute 
DTPFIELD-Syntax error found 
DTPFIELD-Pointer not pointing to a valid field 
DTPFIELD-Could not allocate parse space 
DTPFIELD-No Image with same number found 
DTPFIELD-No Field to Image relationships 


et eeema eae eae pointer Incremented to 
ar 

DTPFIELD-Invalid user defined function or In- 
valid field symbol name 

DTPFIELD-Could not allocate memory for mask 
text 

DTPFIELD-Syntax error in mask definition 
DTPFIELD-Could not allocate space for doda 
symbol names 

DT could not open d-tree Script File 

DT no valid keyword found in script 

DT calloc for parsing buffer allocation 
DTPIMAGE-Could not Allocate Parse space 
DTPIMAGE-Invalid Optional Feature 
DTPIMAGE-Could not allocate space for DODA 
DTPIMAGE-Could not allocate space for DODA 
symbolic names text 

DTPIMAGE-INPUT ADVANCE option invalid 
DTPIMAGE-There must be a space between 
input field and constant field 

DT GENRL called with invalid table 

DT GENRL could not allocate space for sym- 
bolic names 

DT GENRL could not allocate space for sym- 
bolic name text 

DT IMGOT-invalid image number 

DT IMGOT-image has no fields 
DT_IMGOT-Could not open print file 
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e ERR_1904 0x1904 
e ERR_1905 0x1905 


e ERR_ 2301 0x2301 
e ERR 2401 0x2401 
e ERR_ 2501 0x2501 
e ERR 2601 0x2601 
e ERR 2602 0x2602 
e ERR 2901 0x2901 


e ERR 3101 0x3101 


e@e ERR 3102 0x3102 


e ERR 3201 0x3201 
e ERR 3301 0x3301 


e ERR 3701 0x3701 
e ERR 3702 0x3702 
e ERR 3801 0x3801 


e ERR 3802 0x3802 
e ERR 3803 0x3803 
e ERR_ 3804 0x3804 
e ERR 3805 0x3805 
e ERR_ 3806 0x3806 
» ERR_ 3807 0x3807 


e ERR_3808 0x3808 
e ERR 3809 0x3809 
e ERR_ 380A 0x380A 


e ERR_3901 0x3901 


e ERR 3902 0x3902 
e ERR 3903 0x3903 


e ERR 3904 0x3904 


DT _IMGOT-Tried to Use TEMPP type that is al- 
ready in use 

DT IMGOT-Could not allocate TEMPP type 
space for print screen option 

DT CLEAR-invalid screen coordinates 

DT LOCAT-invalid screen coordinates 

DT _FLDIN-Input Longer than DT FLDLN 

DT _IMGIN-invalid image number 

DT _IMGIN-image has no fields 

DT INITL-First & last field name not found in 
DODA. 

DT VLOUT-Could not allocate enough space 
for variable length packed buffer. 

DT _VLOUT-Could not find first variable length 
field in doda. Make sure that fixed record por- 
tion matches record length. 

DT _VLINN-REDVREC failed. 

DT UNPAK-Could not find first variable length 
field in doda. Make sure that fixed record por- 
tion matchesrecord length. 

DT_DELET-delete position beyond end of string 
DT DELET-triing to delete to many characters 
DTPPRMPT-Couid not allocate space for 
prompt 

DTPPRMPT-Could not allocate space for rela- 
tions 

DTPPRMPT-Invalid keyword-define 

USES _IMAGE(?) 

DTPPRMPT-Image number/name not defined 
correctly. 

DTPPRMPT-Key symbol name not in ISAM 
definition. 

DTPPRMPT-Field symbol name not found in 
DODA. 

DTPPRMPT-FIELD defined not on IMAGE 
defined. 

DTPPRMPT-Could not allocate space for prefix 
DTPPRMPT-Scann Number not defined 
DTPPRMPT-Scann Number must be defined 
before target fields 

DTPSCANN-Could not allocate space for 
SCANN 

DTPSCANN-Invalid SCANN option defined 
DTPSCANN-IMAGE OUT image no not a 
defined IMAGE. | 

DTPSCANN-must have valid IMAGE_ROL im- 
ageno 
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e ERR 3905 0x3905 


e ERR 4001 0x4001 
e ERR 4002 0x4002 
e ERR 4003 0x4003 


e ERR 4004 0x4004 


e ERR 4005 0x4005 
e ERR 4101 0x4101 


e ERR_4102 0x4102 
e ERR 4103 0x4103 


e ERR 4501 0x4501 
e ERR 4601 0x4601 


e ERR 4602 0x4602 


e ERR_ 4603 0x4603 
e ERR_ 4604 0x4604 


e ERR 4605 0x4605 
e ERR_ 4701 0x4701 
e ERR 4901 0x4901 
e ERR 5401 0x5401 
e ERR 5501 0x5501 


e ERR 5502 0x5502 
e ERR 5503 0x5503 
e ERR 5504 0x5504 
e ERR 5505 0x5505 
e ERR 5506 0x5506 
e ERR 5507 0x5507 
e ERR 5508 0x5508 
e ERR 5509 0x5509 


e ERR 5510 0x5510 
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DTPSCANN-must have valid IMAGE_INP im- 
ageno 

DT PRMPT-Prompt number not defined 

DT _PRMPT-Associated IMAGE not found 


DT PRMPT-Prompt not found in extracted sub- 
set 

DT PRMPT-Target fields not found for target 
build 

DT PRMPT-Could not allocate space for extract 
DT SCANN-scann number not a defined by 
SCAN 

DT SCANN-IMAGE_ OUT display failed 

DT SCANN-EQLREC failed on previous dis- 
played rcd. 

DT _XTRCT-Could not allocate extract space 
DTPCONST-Image number for constant not 
defined 

DTPCONST-Token not a valid constant or at- 
tribute 

DTPCONST-Invalid output attribute 
DTPCONST-Attribute does not refer to any con- 
stant 

DTPCONST-Could not allocate space for extract 


DT_IMGMV-imageno not a defined IMAGE. 
DT SCGET-EQLREC FAILED. 
DT COMPL-Could not rewrite text file 


DTPSUBFL-Could not allocate space for subfile 
definition 

DTPSUBFL-Could not allocate space for 
relationships 

DTPSUBFL-Parse is expecting to see a subfile 
keyword-syntax error 

DTPSUBFL-Parse cannot determain what sfl 
keyword is being parsed-syntax error 
DTPSUBFL-SFL_IMAGE number/name not 
defined correctly. 

DTPSUBFL-Invalid Number for MAX RECORDS 
value. 

DTPSUBFL-Invalid Number for SFL_LINES 
value. 

DTPSUBFL-SFL_IMAGE must be define before 
SFL_TARGET 

DTPSUBFL-SFL_RECORDS must be define 
before SFL_TARGET 

DTPSUBFL-SFL_LINES must be define before 
SFL_TARGET 
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e ERR_5511 0x5511 
e ERR_5512 0x5512 
e ERR_ 5513 0x5513 
e ERR_ 5514 0x5514 
e ERR_5515 0x5515 
e ERR 5516 0x5516 
e ERR_5517 0x5517 
e ERR_ 5518 0x5518 
e ERR_ 5519 0x5519 
e ERR_5520 0x5520 


e ERR 5521 0x5521 
e ERR_5601 0x5601 
e ERR_5602 0x5602 
e ERR_5603 0x5603 
e ERR_5801 0x5801 
e ERR_5901 0x5901 
e ERR_5902 0x5902 
e ERR_5903 0x5903 


e ERR 5904 0x5904 
e ERR _ 6001 0x6001 
e ERR _ 6002 0x6002 
e ERR_6003 0x6003 


e ERR_6101 0x6101 
e ERR_ 6102 0x6102 
e ERR_ 6201 0x6201 
e ERR_ 6202 0x6202 
e ERR_ 6203 0x6203 
e ERR_6204 0x6204 


e ERR 6205 0x6205 
e ERR 6206 0x6206 
e ERR 6207 0x6207 


e ERR 6401 0x6401 
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DTPSUBFL-Key symbol name not in ISAM 

definition. 

DTPSUBFL-Syntax error-looking for Key symbol 

name 

id ieee symbol name not found in 
oda. 

DTPSUBFL-Only one SFL_TARGET definition al- 

lowed 

DTPSUBFL-SFL_MAP Field symbol name not 

found in doda. 

ape ene length longer than child 
ie 

DTPSUBFL-SFL_TARGET must define target 

field or prefix 

DTPSUBFL-SFL_MUSTHAVE field not found in 

DODA 

DTPSUBFL-SFL_BOUNDARY field not found in 

DODA 

DTPSUBFL-SFL_PARENT-subfile parent not 

defined 

DTPSUBFL-SFL_ATTR-invalid subfile attribute 

DT SFLLD-Could not allocate space for subfile 

DT SFLLD-Memory Block Option is Invalid 

DT SFLLD-Could not Create Disk Subfile 

DT SFLAD-Could not allocate space for extract 

DT SFHLD-Invalid subfile number. 

DT SFHLD-Could not allocate extract space 

er oe not allocate memory control 
Oc 

DT SFHLD-Ocur Number out of range 

DT SFHDL-Invalid subfile number. 

DT SFHDL-Subfile not allocated 

DT _SFHDL-No of records loaded into subfile 

not same as the number that where deleted 

DT SFHAD-Invalid subfile number. 

DT SFHAD-Subfile not allocated 

DT SFLOT-Invalid subfile number. 

DT SFLOT-Subfile not allocated. 

DT SFLOT-Must pass record number 

DT SFLOT-Record number greater than max 

records 

DT SFLOT-Imvalid image number for subfile 

DT SFLOT-Child subfile number invalid 

DT SFLOT-parent record number is child oc- 

curances 

DT SUBFL-Invalid Subfile Number. 
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e ERR 6402 0x6402 
e ERR 6403 0x6403 
e ERR 6404 0x6404 


e ERR 6601 0x6601 
e ERR 6602 0x6602 


e ERR 6603 0x6603 


e ERR 6604 0x6604 
e ERR 6605 0x6605 
e ERR 6606 0x6606 
e ERR 6607 0x6607 
e ERR 6608 0x6608 


e ERR_6609 0x6609 


e ERR_6701 0x6701 
e ERR_ 6801 0x6801 


e ERR_6802 0x6802 


e ERR_6803 0x6803 
e ERR 6804 0x6804 
e ERR 7101 0x7101 


e ERR_7102 0x7102 
e ERR_7103 0x7103 


e ERR_7201 0x7201 
e ERR_7202 0x7202 
e ERR_7203 0x7203 


e ERR 7701 0x7701 
e ERR 7702 0x7702 
e ERR_7703 0x7703 
e ERR 7704 0x7704 
e ERR 7705 0x7705 


e ERR_7801 0x7801 
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DT SUBFL-Subfile Not Allocated. 
DT SUBFL-Invalid Image define for Subfile. 


DT SUBFL-Could not allocate temporary save 
space 

DTPEDITS-Could not allocate EDITS structure 
DTPEDITS-Could not allocate memory for 
EDITS text 

DTPEDITS-Could not allocate EDITS’s RELAT 
memory : 

DTPEDITS-Edit type must follow edit text 
DTPEDITS-Edit Type must follow field name 
DTPEDITS-Must enter message text 
DTPEDITS-field not found on associated image 
DTPEDITS-DUPKEY edit must have key no or 
name 

DTPEDITS-DUPKEY key symbol length to short 
ex: key symbol= "ky" and the key number it 
represents is "100". The "ky" is only 2 digits, the 
"100" is 3 digits. Due to memory allocation this 
is invalid 

DT EDITS-Memory Allocation error on extract 
DT ALIGN-Calculated address not same as 
DODA 


DT ALIGN-First & last field name not found in 
DODA. 

DT ALIGN-Record length in IFIL not correct 

DT ALIGN-Could Not Allocate Field Memory 
DTPKEYBD-Could not allocate space for key se- 
quence 

DTPKEYBD-Syntax error in TERMCAP definition 
DTPKEYBD-DT MXSEQ not large enough in 
dt_typdf.h 

DT KEYBD-Could not open TERMCAP file 

DT KEYBD-Terminal not found in TERMCAP file 
DT_KEYBD-Could not allocate temporary pars- 
ing space 

DTPDFALT-Could not allocate DFALT structure 
space 

DTPDFALT-Could not allocate memory for 
DFALT text 

DTPDFALT-Could not allocate DFALT’s RELAT 
space 

DTPDFALT-Error-Default type must follow field 
name 

DTPDFALT-Stntax error-invalid field symbol 
name. 

DT DFALT-Memory Allocation error on extract 
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e ERR 7901 0x7901 


e ERR_ 801 0x801 
e ERR_802 0x802 
e ERR 803 0x803 
e ERR_804 0x804 


e ERR_ 805 0x805 
e ERR_ 806 0x806 


e ERR_ 807 0x807 
e ERR 808 0x808 
e ERR_809 0x809 


e ERR 811 0x811 
e ERR 812 0x812 
e ERR _ 813 0x813 
e ERR 814 0x814 


e ERR 8801 0x8801 
e ERR_ 8802 0x8802 


e ERR 8803 0x8803 


e ERR 891 0x891 
e ERR 892 0x892 
e ERR_ 893 0x893 
e ERR 901 0x901 
e ERR 902 0x902 
e ERR 903 0x903 
e ERR 921 0x921 
e ERR 922 0x922 


e ERR 951 0x951 
e ERR 952 0x952 
e ERR_ 953 0x953 


e ERR 954 0x954 
e ERR 955 0x955 
e ERR 956 0x956 
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DT NSERT-Position to insert chararacter is 
passed end of string 

DTPIFILS-Unable to allocate IFILS structures 
DTPIFILS-Unable to allocate IIDXS structures 
DTPIFILS-Unable to allocate ISEGS structures 
DTPIFILS-Unable to allocate space for text infor- 
mation 

DTPIFILS-Syntax error-Must have IFILS symbol 
DTPIFILS-Field defined as key segment not in 
DODA 

DTPIFILS-Field defined first or last field not in 
DODA 

DTPIFILS-Field defined as first variable length 
field is not in DODA 

DTPIFILS-Must define KEY NAME before defin- 
ing DUPS OK 

DT_IFILS-Invalid first field name 
DT_IFILS-Invalid last field name 

DT _IFILS-First and last field out of order 

DT IFILS-offset id for segment not between first 
and last fields of file 

DT STALN-COUNT, UCOUNT or POINTER are 
not correctly sized. Call Faircom 

DT STALN-This machine addresses 32 bit 
words (not bytes). Call FairCom 

DT _STALN-This machine addresses words. (not 
bytes). Call FairCom 

DT DODTS-Could not open base script 

DT DODTS-Could not write temp dtree script 
DT DODTS-Could not open user script 

DT DORTS-Could not write new r-tree script 
DT DORTS-Could not open d-tree script 

DT DORTS-Could not find master screen 

DT DFIMG-Image number passed is not defined 
DT DFIMG-Could not allocate memory for ex- 
tract 

DTPMAPIT-Must have an even number of fields 
defined 

DTPMAPIT-Could not allocate space for MAP re- 
lates 

DTPMAPIT-Invalid Source Token-Not field name 
or CALCS name 

DTPMAPIT-copy length longer than child field 
DTPMAPIT-Must Define VALID Map Type 


DTPMAPIT-destination field symbol name not 
found in doda. 
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e ERR 957 0x957 


e ERR_961 0x961 
e ERR_971 0x971 
e ERR_ 972 0x972 
e ERR 9801 0x9801 


e ERR 9802 0x9802 
e ERR_9803 0x9803 
e ERR 9804 0x9804 


e ERR 9805 0x9805 
e ERR_ 9806 0x9806 


e ERR 9807 0x9807 
e ERR 9808 0x9808 


e ERR_9809 0x9809 
e ERR 9810 0x9810 
e ERR 9811 0x9811 


e ERR_1B01 0x1B01 


e ERR 1D01 0x1D01 
e ERR 1D02 0x1D02 
e ERR_1D03 0x1D03 
e ERR_1E01 0x1E01 
e ERR_1E02 0x1E02 
e ERR_1E£03 0x1E03 
e ERR_1E04 0x1E04 
e ERR Alt OxA11 
e ERR A12 0xA12 
e ERR_A13 0xA13 
e ERR_A14 0xA14 
e ERR_A15 OxA15 


e ERR _A16 OxA16 
e ERR A17 0xA17 
e ERR A18 0xA18 
e ERR A19 0xA19 
e ERR A1A OxA1A 
e ERR A1B 0xA1B 
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DTPMAPIT-destination field symbol name not 
on screen 
DT MAPIT-Could not allocate space for extract 


DTPCREAT-Could not allocate space for IFIL 
DTPCREAT-Syntax error 

DTCOPCAT-Could not allocate space for 
CTFILE 

DTCOPCAT-Could not open catalog table file 
DTCOPCAT-Could not allocate space for IFIL 


DTCOPCAT-Could Not read definition record 
from catalog TABLE file 
DTCOPCAT-Could not open ifils 


DTCOPCAT-Could not find any TABLE column 
records 

DTCOPCAT-Could not allocate space for 
catalog DODA 

DTCOPCAT-Could not read catalog index defini- 
tions 

DTCOPCAT-Could not allocate space for IIDX 


DTCOPCAT-Could not allocate space for ISEG 
DTCOPCAT-Index column name not found in 
DODA 

DT SFLNW-Could not allocate space for new 
subfile 

DT SFCLD-Invalid Parent subfile 

DT SFCLD-Invalid Child subfile 

DT SFCLD-Parent not yet allocated 

DT SFCAD-Invalid Parent subfile 

DT SFCAD-Parent not yet allocated 

DT SFCAD-Invalid child subfile 

DT SFCAD-child not yet allocated 
DTCATINC-Unable to initlize display subfile 
DTCATINC-Display subfile number not defined 
DTCATINC-Invalid index subfile number 
DTCATINC-Invalid segment subfile number 


DTCATINC-Invalid fields or column subfile num- 
ber 
DTCATINC-Could not allocate IFIL space 


DTCATINC-Could not allocate IIDX space 
DTCATINC-Could not allocate ISEG space 
DTCATINC-Could not allocate text space 
DTCATINC-Could not open temp text work file 
DTCATINC-DTCATDOD Error see uerr_cod 
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e ERR A21 0xA21 


e ERR A22 0xA22 
e ERR A23 0xA23 
e ERR A24 0xA24 
e ERR _A25 0xA25 
e ERR_A26 0xA26 
e ERR _A27 0xA27 
e ERR_A31 0xA31 
e ERR A32 0xA32 
e ERR A33 0xA33 


e ERR_A51 0xA51 
e ERR_A52 0xA52 
e ERR_A53 0xA53 


e ERR_A54 0xA54 
2 ERR_A55 0xA55 


e ERR_A56 OxA56 
e ERR_A57 0xA57 
e ERR_AS58 0xA58 
e ERR_A59 0xA59 
e ERR_ASA OxA5A 
e ERR_ASB OxA5B 


e ERR 5E1 Ox5E1 
e ERR 5E2 0x5E2 


e ERR _5E3 0x5E3 
e ERR 5E4 0x5E4 
e ERR 5E5 0x5E5 


e ERR_5E6 0x5E6 
@ ERR_5E7 0x5E7 
e ERR 5F1 Ox5F1 
e@ ERR_5F2 0x5F2 
e ERR 6C1 Ox6C1 
e ERR _6C2 0x6C2 
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DTCATPAR-Could not open temporary text 
work file 

DTCATPAR-Could not initialize work subfile. 
DTCATPAR-Work subfile not defined 
DTCATPAR-Could not find index subfile 
DTCATPAR-Could not find segment subfile 
DTCATPAR-Could not find column subfile 
DTCATPAR-DTCATDOD error see uerr_ cod 
DTCATDOD-Invalid subfile number 
DTCATDOD-Could not allocate space for DODA 
DTCATDOD-Could not allocate space for DODA 
name txt 

DTCATADI-Program/Version not found in 
Program Dictionary 

DTCATADI-Program Has No Relationships in 
RELATE Dictionary 

DTCATADI-Ability record pointed to by entry 
from the relate dictionary not found 
DTCATADI-Could Not Allocate space for Abilitys 
DTCATADI-Invalid Ability type found in relate 
entry 

DTCATADI-Ability record pointed to by relate 
entry has zero length 

DTCATADI-Delete of Ability dictionary record 
failed-see uerr cod 

DTCATADI-Delete of Relate Dictionary record 
failed see-uerr_ cod 

DTCATADI-Delete of Program Dictionary record 
failed-see uerr_cod. 

DTCATADI-Could not determine Dictionary file 
numbers 

DTCATADI-Program Has No Relationships in 
ABILITY Dictionary 

DTPMENUS-Space Allocation Error 
DTPMENUS-Menu Call type must follow input 
criteria. 

DTPMENUS-Must enter Compare Criteria 
DTPMENUS-Must enter Call Text 
DTPMENUS-CURSOR = symbol..symbol not in 
DODA 

DTPMENUS-Field compare symbol not in DODA 
DTPMENUS-Must define USES IMAGE first 

DT MENUS-Invalid MENUS number 

DT MENUS-Invalid Image number 

DT REFMT-Space Allocation error 


DT _REFMT-Could not Open Source file 


eee 
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e ERR _6C3 0x6C3 


e ERR 6C4 0x6C4 
e ERR 6C5 0x6C5 
e ERR _6C6 0x6C6 


e ERR _6C7 0x6C7 


e ERR 6C8 0x6C8 
e ERR 6C9 0x6C9 


e ERR_6CA 0x6CA 
e ERR _6CB Oc6CB 


e ERR 6D1 Ox6D1 
e ERR_6D2 0x6D2 
e ERR GE1 Ox6E1 
e ERR_6E2 0x6E2 
e ERR _6E3 0x6E3 
e ERR_6E5 Ox6E5 
e ERR_6E6 Ox6E6 
e ERR_6E7 0x6E7 
e ERR 6F1 Ox6F1 


e ERR_6F2 0x6F2 
e ERR_6F3 Ox6F3 
e ERR_6F4 Ox6F4 


e ERR_6F5 Ox6F5 
e ERR 6F6 Ox6F6 


e ERR_6F7 Ox6F7 


e ERR_6F8 Ox6F8 
e ERR _6F9 Ox6F9 


e ERR_6FA Ox6FA 
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DT REFMT-Doda Length Does not match 
Source File 
DT REFMT-Source file not a data file 


DT _REFMT-Source file Corrupt at open 


DT REFMT-Could not read File header informa- 
tion 

DT REFMT-Could not read Variable length 
record six byte header 

DT REFMT-Source record READ error 

DT REFMT-Write of Null Header failed after for- 
mat 

Destination found to be fixed when rebuilding 
variable length file. 

Destination found to be variable when rebuild- 
ing fixed length file. 

DT DFINI-Invalid Default Number 

DT DFINI-Memory Allocation error on extract 
DT RTREE-r-tree number not defined 

DT RTREE-Associated IMAGE not found 

DT _RTREE-r-tree not found in extracted subset 
DT RTIREE-Could not allocate space for extract 
DT RTREE-Could not open script work file 

DT RTREE-Could not open base script file 
DTPRTREE-Could not allocate space for r-tree 
definition 

DTPRTREE-Could not allocate space for rela- 
tions 

DTPRTREE-Invalid definition keyword-define 
USES IMAGE(?) or define USES SCRIPT(?) 
DTPRTREE-Must define USES IMAGE and 
RUN MSG USES SCRIPT properly Check for 
valid image number or that you have not 
defined both keywords properly 
DTPRTREE-Invalid r-tree keyword 
DTPRTREE-Field symbol name not found in 
DODA. 

DTPRIREE-FIELD defined not on IMAGE 
defined. 

DTPRTREE-Could not allocate space for text 
DTPRTREE-One of the following keyword has a 
syntax error: 

USES _IMAGE(??) 

USES SCRIPT(??) 

REPORT PROGRAM(??) 

CALL_TYPE(??) 

DTPRTREE-Must define substitution text 
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e ERR_6FB Ox6FB 
e ERR 7C1 0x7C1 
e ERR 7C2 0x7C2 


e ERR 821 0x821 
e ERR 822 0x822 


e ERR 841 0x841 
e ERR 842 0x842 


e ERR 843 0x843 


e ERR 851 0x851 
e ERR 852 0x852 


e ERR 7D1 0x7D1 
e ERR_7D2 0x7D2 


e ERR _7E1 Ox7E1 
e ERR _7E2 0x7E2 


e ERR 1011 0x1011 
e ERR 1012 0x1012 
e ERR 1013 0x1013 
e ERR 1014 0x1014 
e ERR 1015 0x1015 


e ERR_1016 0x1016 
e ERR_1071 0x1071 


e ERR_1072 0x1072 
e ERR 1081 0x1081 


e ERR _ 1082 0x1082 
e ERR 1031 0x1031 
e ERR_ 1032 0x1032 
e ERR 1034 0x1034 
e ERR 1041 0x1041 
e ERR _ 1051 0x1051 
e ERR _ 1052 0x1052 
e ERR_ 1053 0x1053 
e ERR_1054 0x1054 
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DTPRTREE-Invalid Call Type 
DTPTABLE-Space Allocation Error 
DTPTABLE-Syntax Error. Disk representation 
and screen representation must be defined 
before fields 

DTPCALCS-Space Allocation Error 
DTPCALCS-Expression to long for postfix con- 
vertion- change DTMXWORK in DTPCALCS 
DTPHELPP-Space Allocation Error 
DTPHELPP-Syntax Error. Help text or token 
must be defined before fields 
DTPHELPP-Syntax Error. USES SFL not define 
correctly 

DT HELPP-Could not initlize help text subfile 
DT _HELPP-Subfile defined for help text not 
found 

DT GHELP-Token used to get help text not 
defined in help text file 

DT _GHELP-File Open error. One of the needed 
file could not be opened. See uerr_cod. 

DT _BHELP-Could Not Open help text file 

DT _BHELP-Could Create new index file. See 
uerr cod. 

DTPHOOKS-Memory Allocation Error. 
DTPHOOKS-Must define valid hook location 
DTPHOOKS-Invalid Field Name for cur_field 
DTPHOOKS-Invalid Function name 
DTPHOOKS - invalid image name foe 
cur_image. 

invalid keystroke for cur_keybd. 
DT_GPINN-Could not alloc memory for group 
record 

DT_GPINN-SIZEOF for ability type found to be 
zero make sure that DT _SETTY(1) was called. 
DTPGROUP-Could not allocate memory for 
group 

DTPGROUP-Invalid Optional Definition 
DT_FLATI-Could not open error log file 
DT_FLATI-Could not open flat file 
DT_FLATI-Could not open error log file 

DT FLATO-Could not open Flat File 
DT_GPOUT-Could not write group to disk 
DT_GPOUT - Could not write control record. 
DT_GPOUT - Ability record has zero length. 
DT_GPOUT - Unable to delete out old definition. 
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e ERR_ 1071 0x1071 DT _GPINN - Could not allocate memory for 
group record. 

e ERR_ 1072 0x1072 DT GPINN - SIZEOF for ability type found to be 
zero make sure that DT _SETTY(1) has been 


called. 

e ERR_ 1073 0x1073 DT GPINN - Could not read master control 
record. 

e ERR_ 1074 0x1074 DT GPINN - No abilities found in file for this 
group. 

e ERR _A6i OxA61 DTCATCSP-Could not open work file 


e ERR 1061 0xA1061 DTCATDIF-Could not open work file 
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, Abilities 
memory swapping 7-21 
Ability 
adding a new ability 9-1 - 9-12 
HELP - Help Text 7-23 - 7-28 
HOOKS - user defined logic hooks 7-29 - 7-32 
IFILS - incremental files 7-33 - 7-36 
IMAGE - screen image 7-37 - 7-42 
interpreted & hard coded together 4-11 - 4-14 
MAP - map (copy) data from field to field 7-43 - 7-46 
MENUS - menu managment 7-47 - 7-50 
PROMPT - data base access prompt 7-51 - 7-54 
reference numbers 7-6 
RTREE - r-tree interface 7-55 - 7-62 
SCAN - scan or browse data base 7-63 - 7-66 
TABLES - alternate data representaion 7-77 - 7-80 
Vow’ what is an ability 4-2, 7-i 
Ability Dictionary 7-21 
ability global number of occurrences DTIGNUMBR 4-11 
ability global pointer -DTGPOINT 4-11 . 
AFTER_INPUT - hook 7-29 
Auto Dup = 7-5 


B 


BACKGROUND - image background color 7-39 
BASE-ROW - image base row 7-39 

BASE COLUMN - image base column 7-39 
basic screen I/O 4-1 - 4-6 

BEFORE_INPUT - hook 7-29 

BOTTOM - frame side 7-38 


C 


c-tree interface 4-15 - 4-22 

c-tree library requirements 1-2 
CALCS - Calculation Ability 7-1 
calulations used with MAP ability 7-43 
Catalog - tutorial 2-21 - 2-36 

catalog function keys 3-8 - 3-10 
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Catalog instructions 3-1 - 3-3 

clear screen - relax 7-39 

CLR_BLOCK - clear image block 7-39 

CLR EXIT - clear block upon image exit 7-39 
CLR_LINES - image input processing 7-39 
Color Attributes 7-3 

color support 5-2 

CONST - Constant Attributes 7-3 

constants fields 7-37 


conversion 
interpreted to hard coded abilities 4-7 - 4-10 
copy data elements- map data 7-43 


cur field - current field 7-30 

cur_image - current image 7-30 

cur_keybd - current keystoke 7-30 

current working directory-display 7-38 

cursor control (flow) 7-19 

CWD - @CWD - display current work’n directory 7-38 


D 

data dictionary 3-4 - 3-5 

access from d-tree script 7-33 
_ DATE - @DATE - display system date 7-38 
DEFAULTS - define default values for a field r 
DF_DFALT - default a field 7-8 
DFALT_KEY - default key 7-5 
DFINI - default init function 7-6 
DODA - data oject definition array 4-15 
DT _ADREC - adding data to c-tree database 4-20 
DT_ ALIGN - set record buffers4-16 
DT. _COMPL - create include file for abilities 4-7 
DT: _DFIMG - Default Image Fields 7-8 
DT _DLREC - delete data from c-tree 4-20 
DT | _GPINN - group in 7-22 
DT _GPOUT - group out 7-22 
DT_IFILS - open incremental files 4-20 
DT_INAME - return ability def section number 7 
DT RWREC - rewrite record 4-20 
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E 

EDITS 

DATE _XXXX - date validation 7-12 

define an edit for a field 7-11 

DUPKEY - duplicate keys 7-12 

edit types 7-11 

error messages /7-11 

MAND FILL - madatory fill 7-12 

MANDATORY - mandatory entry 7-12 

SFLHASH - hash totals 7-13 

SFLNOTSAME - validate subfile entry 7-14 

SFLSAME - check subfile entry 7-13 

TABLE - table validation7-12 

VALIDATE - validate from data base 7-12 
edits - addinga new 9-17 


cE 


FIELD 
Color Attributes 7-18 
Cursor control (flow) 7-19 
define a field ability 7-17 - 7-20 
input attributes 7-17 
masks 7-19 
Output attributes 7-18 
return a field pointer 7-9 
first and last field names used with d-tree 4-17 
floating point variables on screen = 7-37 
FORGROUND - image forground color 7-39 
Frame Attributes 7-3 
frame sides 7-38 
frame titles 7-38 
frame types 7-38 
frames 7-38 
FSTFLD ADVANCE - image input processing 7-39 


G 


GROUPS - Group Ability 7-21 - 7-22 
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hard coded ability table 4-4 

header files - necessary 4-3 

HELP - Help Ability 7-23 - 7-28 

Help File Access 7-26 

Hook symbol name 7-29 WH 
HOOKS - user defined logic hooks 7-29 - 7-32 

hooks conditions 7-30 


IFILS - incremental files 7-33 - 7-36 
IMAGE 
Default fields 7-8 
IMAGE - screen image ability 7-37 - 7-42 
index definitions 3-6 - 3-7 
indexing a ascii file 7-27 
input attribute - adding a new 9-13 
INPUT ADVANCE - image input processing 7-39 
Installation Procedures 1-1 
Instant Screens (direct video writes-DOS) 1-5 
Instant screens - direct video writting 5-2 


wy 
keyboard initialization 4-9 
LEFT - frame side 7-38 
LSTFLD_ADVANCE - image input processing 7-39 
MAP - map (copy) data from field to field 7-43 - 7-46 
memory utilization7-21 
MENUS - menu management 7-47 - 7-50 
menus - tutorial 2-61 - 2-68 
MESSAGE 
default message line 7-11 
Muli-User Interference 4-17 ~ 


multi-file program -tutorial 2-37 - 2-52 
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NO_CLS - do no clear screen 7-39 


O 


output attribute - adding a new 9-14 - 9-16 
Output Attributes-Constant 7-3 


P 
POP_UP - popup screens 7-39 
portable incremental structures 4-19 
print screens (Unix/Xenix) 5-1 
program initialization 4-9 
PROMPT - data base access prompt 7-51 - 7-54 


R 


r-tree interface - tutorial 2-53 - 2-60 
record access function 4-21 
record buffers 4-15 
3 buffer approach 4-17 
dynamic 4-16 
hard coded 4-16 
record lengths 4-18 
record lock 4-18 
reformat a file 3-13 
relate structure -maps 7-45 
requirement 
what every d-tree program has to have 4-5 
requirements 
what must be done first in a d-tree program 4-5 
RIGHT - frame side 7-38 
RTREE - rtree interface ability 7-55 - 7-62 
RUN program 7-34 


S 


SCAN - scan or browse data base 7-63 - 7-66 
sets - c-tree FRSSET, NXTSET 7-65 
Subfiles 

Used with help text 7-23 
system date7-38 
system time 7-38 
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TABLES - alternate data representaion 7-77 - 7-80 
TERMCAP - terminal and keyboard interface 6-1 - 6-8 
TFRMKEY - forming a target variable 7-51 
TIME - @TIME - display system time7-38 
TOP - frame side 7-38 
typedef 
DTTCALCS - Calculations 7-2 
DTTCONST - Constants fields 7-4 
DTTDFALT - defaults 7-9 
DTTEDITS - edits 7-14 
DTTFIELD - variable fields 7-20 
DTTGROUP - ability groups 7-22 
DTTHELPP - help text 7-24 
DTTHOOKS - user hooks 7-31 
DTTIMAGE - image 7-40 
DTTMENUS - menu managment 7-49 
DTTPRMPT - prompt definition 7-53 
DTTRELAT - relate structure 7-44 
DTTRTREE - rtree front-end 7-61 
DTTTABLE - alternate data representaion 7-78 
IFIL, IDX, ISEG = 7-35 


U 


user define function table 7-30 
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variable fields 7-37 
variable length files 
definition in a script 7-34 
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